idnits 2.17.00 (12 Aug 2021) /tmp/idnits8284/draft-ietf-tls-rfc4346-bis-09.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 15. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 4629. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 4640. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 4647. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 4653. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year == Line 793 has weird spacing: '...gorithm bul...' == Line 2395 has weird spacing: '...ixed_dh a c...' == Line 2396 has weird spacing: '...ixed_dh a c...' == Line 2532 has weird spacing: '...ed_ecdh the...' == Line 3405 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 'SHOULD not' in this paragraph: - Support for the SSLv2 backward-compatible hello is now a MAY, not a SHOULD, with sending it a SHOULD not. Support will probably become a SHOULD NOT in the future. -- 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 326 -- Looks like a reference, but probably isn't: '1' on line 326 -- Looks like a reference, but probably isn't: '3' on line 3908 -- Looks like a reference, but probably isn't: '9' on line 361 -- Looks like a reference, but probably isn't: '2' on line 3130 -- Looks like a reference, but probably isn't: '4' on line 397 -- Looks like a reference, but probably isn't: '8' on line 398 -- Looks like a reference, but probably isn't: '10' on line 508 -- Looks like a reference, but probably isn't: '48' on line 3415 -- Looks like a reference, but probably isn't: '32' on line 3417 == Missing Reference: 'ChangeCipherSpec' is mentioned on line 1671, but not defined -- Looks like a reference, but probably isn't: '28' on line 3126 -- Looks like a reference, but probably isn't: '46' on line 3254 -- 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: draft-mcgrew-auth-enc has been published as RFC 5116 -- 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 3268 (ref. 'TLSAES') (Obsoleted by RFC 5246) -- Obsolete informational reference (is this intentional?): RFC 4492 (ref. 'TLSECC') (Obsoleted by RFC 8422) == Outdated reference: draft-ietf-tls-rfc4366-bis has been published as RFC 6066 -- Obsolete informational reference (is this intentional?): RFC 5081 (ref. 'TLSPGP') (Obsoleted by RFC 6091) Summary: 6 errors (**), 0 flaws (~~), 11 warnings (==), 32 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT Tim Dierks 2 Obsoletes (if approved): RFC 3268, 4346, 4366 Independent 3 Updates (if approved): RFC 4492 Eric Rescorla 4 Intended status: Proposed Standard Network Resonance, Inc. 5 February 2008 (Expires August 2008) 7 The Transport Layer Security (TLS) Protocol 8 Version 1.2 10 Status of this Memo 12 By submitting this Internet-Draft, each author represents that any 13 applicable patent or other IPR claims of which he or she is aware 14 have been or will be disclosed, and any of which he or she becomes 15 aware will be disclosed, in accordance with Section 6 of BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 Copyright Notice 35 Copyright (C) The IETF Trust (2008). 37 Abstract 39 This document specifies Version 1.2 of the Transport Layer Security 40 (TLS) protocol. The TLS protocol provides communications security 41 over the Internet. The protocol allows client/server applications to 42 communicate in a way that is designed to prevent eavesdropping, 43 tampering, or message forgery. 45 Table of Contents 47 1. Introduction 4 48 1.1. Requirements Terminology 5 49 1.2. Major Differences from TLS 1.1 5 50 2. Goals 6 51 3. Goals of This Document 7 52 4. Presentation Language 7 53 4.1. Basic Block Size 7 54 4.2. Miscellaneous 7 55 4.3. Vectors 8 56 4.4. Numbers 9 57 4.5. Enumerateds 9 58 4.6. Constructed Types 10 59 4.6.1. Variants 10 60 4.7. Cryptographic Attributes 11 61 4.8. Constants 13 62 5. HMAC and the Pseudorandom Function 14 63 6. The TLS Record Protocol 15 64 6.1. Connection States 16 65 6.2. Record layer 18 66 6.2.1. Fragmentation 19 67 6.2.2. Record Compression and Decompression 20 68 6.2.3. Record Payload Protection 21 69 6.2.3.1. Null or Standard Stream Cipher 21 70 6.2.3.2. CBC Block Cipher 22 71 6.2.3.3. AEAD ciphers 24 72 6.3. Key Calculation 25 73 7. The TLS Handshaking Protocols 26 74 7.1. Change Cipher Spec Protocol 27 75 7.2. Alert Protocol 27 76 7.2.1. Closure Alerts 28 77 7.2.2. Error Alerts 29 78 7.3. Handshake Protocol Overview 33 79 7.4. Handshake Protocol 36 80 7.4.1. Hello Messages 37 81 7.4.1.1. Hello Request 37 82 7.4.1.2. Client Hello 38 83 7.4.1.3. Server Hello 41 84 7.4.1.4 Hello Extensions 42 85 7.4.1.4.1 Signature Algorithms 43 86 7.4.2. Server Certificate 45 87 7.4.3. Server Key Exchange Message 47 88 7.4.4. Certificate Request 50 89 7.4.5 Server hello done 51 90 7.4.6. Client Certificate 52 91 7.4.7. Client Key Exchange Message 54 92 7.4.7.1. RSA Encrypted Premaster Secret Message 54 93 7.4.7.2. Client Diffie-Hellman Public Value 57 94 7.4.8. Certificate verify 58 95 7.4.9. Finished 58 96 8. Cryptographic Computations 60 97 8.1. Computing the Master Secret 60 98 8.1.1. RSA 61 99 8.1.2. Diffie-Hellman 61 100 9. Mandatory Cipher Suites 61 101 10. Application Data Protocol 61 102 11. Security Considerations 61 103 12. IANA Considerations 61 104 A. Protocol Constant Values 64 105 A.1. Record Layer 64 106 A.2. Change Cipher Specs Message 65 107 A.3. Alert Messages 65 108 A.4. Handshake Protocol 66 109 A.4.1. Hello Messages 66 110 A.4.2. Server Authentication and Key Exchange Messages 68 111 A.4.3. Client Authentication and Key Exchange Messages 69 112 A.4.4. Handshake Finalization Message 70 113 A.5. The Cipher Suite 70 114 A.6. The Security Parameters 72 115 A.7. Changes to RFC 4492 73 116 B. Glossary 73 117 C. Cipher Suite Definitions 78 118 D. Implementation Notes 80 119 D.1 Random Number Generation and Seeding 80 120 D.2 Certificates and Authentication 80 121 D.3 Cipher Suites 80 122 D.4 Implementation Pitfalls 80 123 E. Backward Compatibility 83 124 E.1 Compatibility with TLS 1.0/1.1 and SSL 3.0 83 125 E.2 Compatibility with SSL 2.0 84 126 E.3. Avoiding Man-in-the-Middle Version Rollback 86 127 F. Security Analysis 87 128 F.1. Handshake Protocol 87 129 F.1.1. Authentication and Key Exchange 87 130 F.1.1.1. Anonymous Key Exchange 87 131 F.1.1.2. RSA Key Exchange and Authentication 88 132 F.1.1.3. Diffie-Hellman Key Exchange with Authentication 88 133 F.1.2. Version Rollback Attacks 89 134 F.1.3. Detecting Attacks Against the Handshake Protocol 90 135 F.1.4. Resuming Sessions 90 136 F.2. Protecting Application Data 90 137 F.3. Explicit IVs 91 138 F.4. Security of Composite Cipher Modes 91 139 F.5 Denial of Service 92 140 F.6 Final Notes 92 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. Signed elements now include a field 214 that explicitly specifies the hash algorithm used. 216 - Substantial cleanup to the clients and servers ability to specify 217 which hash and signature algorithms they will accept. Note that 218 this also relaxes some of the constraints on signature and hash 219 algorithms from previous versions of TLS. 221 - Addition of support for authenticated encryption with additional 222 data modes. 224 - TLS Extensions definition and AES Cipher Suites were merged in 225 from external [TLSEXT] and [TLSAES]. 227 - Tighter checking of EncryptedPreMasterSecret version numbers. 229 - Tightened up a number of requirements. 231 - Verify_data length now depends on the cipher suite (default is 232 still 12). 234 - Cleaned up description of Bleichenbacher/Klima attack defenses. 236 - Alerts MUST now be sent in many cases. 238 - After a certificate_request, if no certificates are available, 239 clients now MUST send an empty certificate list. 241 - TLS_RSA_WITH_AES_128_CBC_SHA is now the mandatory to implement 242 cipher suite. 244 - Added HMAC-SHA256 cipher suites 246 - Removed IDEA and DES cipher suites. They are now deprecated and 247 will be documented in a separate document. 249 - Support for the SSLv2 backward-compatible hello is now a MAY, not 250 a SHOULD, with sending it a SHOULD not. Support will probably 251 become a SHOULD NOT in the future. 253 - Added limited "fall-through" to the presentation language to allow 254 multiple case arms to have the same encoding. 256 - Added an Implementation Pitfalls sections 258 - The usual clarifications and editorial work. 260 2. Goals 262 The goals of TLS Protocol, in order of their priority, are as 263 follows: 265 1. Cryptographic security: TLS should be used to establish a secure 266 connection between two parties. 268 2. Interoperability: Independent programmers should be able to 269 develop applications utilizing TLS that can successfully exchange 270 cryptographic parameters without knowledge of one another's code. 272 3. Extensibility: TLS seeks to provide a framework into which new 273 public key and bulk encryption methods can be incorporated as 274 necessary. This will also accomplish two sub-goals: preventing the 275 need to create a new protocol (and risking the introduction of 276 possible new weaknesses) and avoiding the need to implement an 277 entire new security library. 279 4. Relative efficiency: Cryptographic operations tend to be highly 280 CPU intensive, particularly public key operations. For this 281 reason, the TLS protocol has incorporated an optional session 282 caching scheme to reduce the number of connections that need to be 283 established from scratch. Additionally, care has been taken to 284 reduce network activity. 286 3. Goals of This Document 288 This document and the TLS protocol itself are based on the SSL 3.0 289 Protocol Specification as published by Netscape. The differences 290 between this protocol and SSL 3.0 are not dramatic, but they are 291 significant enough that the various versions of TLS and SSL 3.0 do 292 not interoperate (although each protocol incorporates a mechanism by 293 which an implementation can back down to prior versions). This 294 document is intended primarily for readers who will be implementing 295 the protocol and for those doing cryptographic analysis of it. The 296 specification has been written with this in mind, and it is intended 297 to reflect the needs of those two groups. For that reason, many of 298 the algorithm-dependent data structures and rules are included in the 299 body of the text (as opposed to in an appendix), providing easier 300 access to them. 302 This document is not intended to supply any details of service 303 definition or of interface definition, although it does cover select 304 areas of policy as they are required for the maintenance of solid 305 security. 307 4. Presentation Language 309 This document deals with the formatting of data in an external 310 representation. The following very basic and somewhat casually 311 defined presentation syntax will be used. The syntax draws from 312 several sources in its structure. Although it resembles the 313 programming language "C" in its syntax and XDR [XDR] in both its 314 syntax and intent, it would be risky to draw too many parallels. The 315 purpose of this presentation language is to document TLS only; it has 316 no general application beyond that particular goal. 318 4.1. Basic Block Size 320 The representation of all data items is explicitly specified. The 321 basic data block size is one byte (i.e., 8 bits). Multiple byte data 322 items are concatenations of bytes, from left to right, from top to 323 bottom. From the bytestream, a multi-byte item (a numeric in the 324 example) is formed (using C notation) by: 326 value = (byte[0] << 8*(n-1)) | (byte[1] << 8*(n-2)) | 327 ... | byte[n-1]; 329 This byte ordering for multi-byte values is the commonplace network 330 byte order or big endian format. 332 4.2. Miscellaneous 333 Comments begin with "/*" and end with "*/". 335 Optional components are denoted by enclosing them in "[[ ]]" double 336 brackets. 338 Single-byte entities containing uninterpreted data are of type 339 opaque. 341 4.3. Vectors 343 A vector (single dimensioned array) is a stream of homogeneous data 344 elements. The size of the vector may be specified at documentation 345 time or left unspecified until runtime. In either case, the length 346 declares the number of bytes, not the number of elements, in the 347 vector. The syntax for specifying a new type, T', that is a fixed- 348 length vector of type T is 350 T T'[n]; 352 Here, T' occupies n bytes in the data stream, where n is a multiple 353 of the size of T. The length of the vector is not included in the 354 encoded stream. 356 In the following example, Datum is defined to be three consecutive 357 bytes that the protocol does not interpret, while Data is three 358 consecutive Datum, consuming a total of nine bytes. 360 opaque Datum[3]; /* three uninterpreted bytes */ 361 Datum Data[9]; /* 3 consecutive 3 byte vectors */ 363 Variable-length vectors are defined by specifying a subrange of legal 364 lengths, inclusively, using the notation . When 365 these are encoded, the actual length precedes the vector's contents 366 in the byte stream. The length will be in the form of a number 367 consuming as many bytes as required to hold the vector's specified 368 maximum (ceiling) length. A variable-length vector with an actual 369 length field of zero is referred to as an empty vector. 371 T T'; 373 In the following example, mandatory is a vector that must contain 374 between 300 and 400 bytes of type opaque. It can never be empty. The 375 actual length field consumes two bytes, a uint16, sufficient to 376 represent the value 400 (see Section 4.4). On the other hand, longer 377 can represent up to 800 bytes of data, or 400 uint16 elements, and it 378 may be empty. Its encoding will include a two-byte actual length 379 field prepended to the vector. The length of an encoded vector must 380 be an even multiple of the length of a single element (for example, a 381 17-byte vector of uint16 would be illegal). 383 opaque mandatory<300..400>; 384 /* length field is 2 bytes, cannot be empty */ 385 uint16 longer<0..800>; 386 /* zero to 400 16-bit unsigned integers */ 388 4.4. Numbers 390 The basic numeric data type is an unsigned byte (uint8). All larger 391 numeric data types are formed from fixed-length series of bytes 392 concatenated as described in Section 4.1 and are also unsigned. The 393 following numeric types are predefined. 395 uint8 uint16[2]; 396 uint8 uint24[3]; 397 uint8 uint32[4]; 398 uint8 uint64[8]; 400 All values, here and elsewhere in the specification, are stored in 401 "network" or "big-endian" order; the uint32 represented by the hex 402 bytes 01 02 03 04 is equivalent to the decimal value 16909060. 404 Note that in some cases (e.g., DH parameters) it is necessary to 405 represent integers as opaque vectors. In such cases, they are 406 represented as unsigned integers (i.e., leading zero octets are not 407 required even if the most significant bit is set). 409 4.5. Enumerateds 411 An additional sparse data type is available called enum. A field of 412 type enum can only assume the values declared in the definition. 413 Each definition is a different type. Only enumerateds of the same 414 type may be assigned or compared. Every element of an enumerated must 415 be assigned a value, as demonstrated in the following example. Since 416 the elements of the enumerated are not ordered, they can be assigned 417 any unique value, in any order. 419 enum { e1(v1), e2(v2), ... , en(vn) [[, (n)]] } Te; 421 Enumerateds occupy as much space in the byte stream as would its 422 maximal defined ordinal value. The following definition would cause 423 one byte to be used to carry fields of type Color. 425 enum { red(3), blue(5), white(7) } Color; 427 One may optionally specify a value without its associated tag to 428 force the width definition without defining a superfluous element. 430 In the following example, Taste will consume two bytes in the data 431 stream but can only assume the values 1, 2, or 4. 433 enum { sweet(1), sour(2), bitter(4), (32000) } Taste; 435 The names of the elements of an enumeration are scoped within the 436 defined type. In the first example, a fully qualified reference to 437 the second element of the enumeration would be Color.blue. Such 438 qualification is not required if the target of the assignment is well 439 specified. 441 Color color = Color.blue; /* overspecified, legal */ 442 Color color = blue; /* correct, type implicit */ 444 For enumerateds that are never converted to external representation, 445 the numerical information may be omitted. 447 enum { low, medium, high } Amount; 449 4.6. Constructed Types 451 Structure types may be constructed from primitive types for 452 convenience. Each specification declares a new, unique type. The 453 syntax for definition is much like that of C. 455 struct { 456 T1 f1; 457 T2 f2; 458 ... 459 Tn fn; 460 } [[T]]; 462 The fields within a structure may be qualified using the type's name, 463 with a syntax much like that available for enumerateds. For example, 464 T.f2 refers to the second field of the previous declaration. 465 Structure definitions may be embedded. 467 4.6.1. Variants 469 Defined structures may have variants based on some knowledge that is 470 available within the environment. The selector must be an enumerated 471 type that defines the possible variants the structure defines. There 472 must be a case arm for every element of the enumeration declared in 473 the select. Case arms have limited fall-through: if two case arms 474 follow in immediate succession with no fields in between, then they 475 both contain the same fields. Thus, in the example below, "orange" 476 and "banana" both contain V2. Note that this is a new piece of syntax 477 in TLS 1.2. 479 The body of the variant structure may be given a label for reference. 480 The mechanism by which the variant is selected at runtime is not 481 prescribed by the presentation language. 483 struct { 484 T1 f1; 485 T2 f2; 486 .... 487 Tn fn; 488 select (E) { 489 case e1: Te1; 490 case e2: Te2; 491 case e3: case e4: Te3; 492 .... 493 case en: Ten; 494 } [[fv]]; 495 } [[Tv]]; 497 For example: 499 enum { apple, orange, banana } VariantTag; 501 struct { 502 uint16 number; 503 opaque string<0..10>; /* variable length */ 504 } V1; 506 struct { 507 uint32 number; 508 opaque string[10]; /* fixed length */ 509 } V2; 511 struct { 512 select (VariantTag) { /* value of selector is implicit */ 513 case apple: 514 V1; /* VariantBody, tag = apple */ 515 case orange: 516 case banana: 517 V2; /* VariantBody, tag = orange or banana */ 518 } variant_body; /* optional label on variant */ 519 } VariantRecord; 521 4.7. Cryptographic Attributes 523 The five cryptographic operations digital signing, stream cipher 524 encryption, block cipher encryption, authenticated encryption with 525 additional data (AEAD) encryption and public key encryption are 526 designated digitally-signed, stream-ciphered, block-ciphered, aead- 527 ciphered, and public-key-encrypted, respectively. A field's 528 cryptographic processing is specified by prepending an appropriate 529 key word designation before the field's type specification. 530 Cryptographic keys are implied by the current session state (see 531 Section 6.1). 533 A digitally-signed element is encoded as a struct DigitallySigned: 535 struct { 536 SignatureAndHashAlgorithm algorithm; 537 opaque signature<0..2^16-1>; 538 } DigitallySigned; 540 The algorithm field specifies the algorithm used (see Section 541 7.4.1.4.1 for the definition of this field.) Note that the 542 introduction of the algorithm field is a change from previous 543 versions. The signature is a digital signature using those 544 algorithms over the contents of the element. The contents themselves 545 do not appear on the wire but are simply calculated. The length of 546 the signature is specified by the signing algorithm and key. 548 In RSA signing, the opaque vector contains the signature generated 549 using the RSASSA-PKCS1-v1_5 signature scheme defined in [PKCS1]. As 550 discussed in [PKCS1], the DigestInfo MUST be DER encoded and for hash 551 algorithms without parameters (which include SHA-1) the 552 DigestInfo.AlgorithmIdentifier.parameters field MUST be NULL but 553 implementations MUST accept both without parameters and with NULL 554 parameters. Note that earlier versions of TLS used a different RSA 555 signature scheme which did not include a DigestInfo encoding. 557 In DSS, the 20 bytes of the SHA-1 hash are run directly through the 558 Digital Signing Algorithm with no additional hashing. This produces 559 two values, r and s. The DSS signature is an opaque vector, as above, 560 the contents of which are the DER encoding of: 562 Dss-Sig-Value ::= SEQUENCE { 563 r INTEGER, 564 s INTEGER 565 } 567 Note: In current terminology, DSA refers to the Digital Signature 568 Algorithm and DSS refers to the NIST standard. For historical 569 reasons, this document uses DSS and DSA interchangeably 570 to refer to the DSA algorithm, as was done in SSLv3. 572 In stream cipher encryption, the plaintext is exclusive-ORed with an 573 identical amount of output generated from a cryptographically secure 574 keyed pseudorandom number generator. 576 In block cipher encryption, every block of plaintext encrypts to a 577 block of ciphertext. All block cipher encryption is done in CBC 578 (Cipher Block Chaining) mode, and all items that are block-ciphered 579 will be an exact multiple of the cipher block length. 581 In AEAD encryption, the plaintext is simultaneously encrypted and 582 integrity protected. The input may be of any length and aead-ciphered 583 output is generally larger than the input in order to accomodate the 584 integrity check value. 586 In public key encryption, a public key algorithm is used to encrypt 587 data in such a way that it can be decrypted only with the matching 588 private key. A public-key-encrypted element is encoded as an opaque 589 vector <0..2^16-1>, where the length is specified by the encryption 590 algorithm and key. 592 RSA encryption is done using the RSAES-PKCS1-v1_5 encryption scheme 593 defined in [PKCS1]. 595 In the following example 597 stream-ciphered struct { 598 uint8 field1; 599 uint8 field2; 600 digitally-signed opaque { 601 uint8 field3<0..255>; 602 uint8 field4; 603 }; 604 } UserType; 606 The contents of the inner struct (field3 and field4) are used as 607 input for the signature/hash algorithm, and then the entire structure 608 is encrypted with a stream cipher. The length of this structure, in 609 bytes, would be equal to two bytes for field1 and field2, plus two 610 bytes for the signature and hash algorithm, plus two bytes for the 611 length of the signature, plus the length of the output of the signing 612 algorithm. This is known because the algorithm and key used for the 613 signing are known prior to encoding or decoding this structure. 615 4.8. Constants 617 Typed constants can be defined for purposes of specification by 618 declaring a symbol of the desired type and assigning values to it. 619 Under-specified types (opaque, variable length vectors, and 620 structures that contain opaque) cannot be assigned values. No fields 621 of a multi-element structure or vector may be elided. 623 For example: 625 struct { 626 uint8 f1; 627 uint8 f2; 628 } Example1; 630 Example1 ex1 = {1, 4}; /* assigns f1 = 1, f2 = 4 */ 632 5. HMAC and the Pseudorandom Function 634 The TLS record layer uses a keyed Message Authentication Code (MAC) 635 to protect message integrity. The cipher suites defined in this 636 document use a construction known as HMAC, described in [HMAC], which 637 is based on a hash function. Other cipher suites MAY define their own 638 MAC constructions, if needed. 640 In addition, a construction is required to do expansion of secrets 641 into blocks of data for the purposes of key generation or validation. 642 This pseudo-random function (PRF) takes as input a secret, a seed, 643 and an identifying label and produces an output of arbitrary length. 645 In this section, we define one PRF, based on HMAC. This PRF with the 646 SHA-256 hash function is used for all cipher suites defined in this 647 document and in TLS documents published prior to this document when 648 TLS 1.2 is negotiated. New cipher suites MUST explicitly specify a 649 PRF and in general SHOULD use the TLS PRF with SHA-256 or a stronger 650 standard hash function. 652 First, we define a data expansion function, P_hash(secret, data) that 653 uses a single hash function to expand a secret and seed into an 654 arbitrary quantity of output: 656 P_hash(secret, seed) = HMAC_hash(secret, A(1) + seed) + 657 HMAC_hash(secret, A(2) + seed) + 658 HMAC_hash(secret, A(3) + seed) + ... 660 Where + indicates concatenation. 662 A() is defined as: 664 A(0) = seed 665 A(i) = HMAC_hash(secret, A(i-1)) 667 P_hash can be iterated as many times as is necessary to produce the 668 required quantity of data. For example, if P_SHA256 is being used to 669 create 80 bytes of data, it will have to be iterated three times 670 (through A(3)), creating 96 bytes of output data; the last 16 bytes 671 of the final iteration will then be discarded, leaving 80 bytes of 672 output data. 674 TLS's PRF is created by applying P_hash to the secret as: 676 PRF(secret, label, seed) = P_(secret, label + seed) 678 The label is an ASCII string. It should be included in the exact form 679 it is given without a length byte or trailing null character. For 680 example, the label "slithy toves" would be processed by hashing the 681 following bytes: 683 73 6C 69 74 68 79 20 74 6F 76 65 73 685 6. The TLS Record Protocol 687 The TLS Record Protocol is a layered protocol. At each layer, 688 messages may include fields for length, description, and content. 689 The Record Protocol takes messages to be transmitted, fragments the 690 data into manageable blocks, optionally compresses the data, applies 691 a MAC, encrypts, and transmits the result. Received data is 692 decrypted, verified, decompressed, reassembled, and then delivered to 693 higher-level clients. 695 Four record protocol clients are described in this document: the 696 handshake protocol, the alert protocol, the change cipher spec 697 protocol, and the application data protocol. In order to allow 698 extension of the TLS protocol, additional record types can be 699 supported by the record protocol. New record type values are assigned 700 by IANA as described in Section 12. 702 Implementations MUST NOT send record types not defined in this 703 document unless negotiated by some extension. If a TLS 704 implementation receives an unexpected record type, it MUST send an 705 unexpected_message alert. 707 Any protocol designed for use over TLS MUST be carefully designed to 708 deal with all possible attacks against it. Note that because the 709 type and length of a record are not protected by encryption, care 710 SHOULD be taken to minimize the value of traffic analysis of these 711 values. 713 6.1. Connection States 715 A TLS connection state is the operating environment of the TLS Record 716 Protocol. It specifies a compression algorithm, an encryption 717 algorithm, and a MAC algorithm. In addition, the parameters for these 718 algorithms are known: the MAC key and the bulk encryption keys for 719 the connection in both the read and the write directions. Logically, 720 there are always four connection states outstanding: the current read 721 and write states, and the pending read and write states. All records 722 are processed under the current read and write states. The security 723 parameters for the pending states can be set by the TLS Handshake 724 Protocol, and the Change Cipher Spec can selectively make either of 725 the pending states current, in which case the appropriate current 726 state is disposed of and replaced with the pending state; the pending 727 state is then reinitialized to an empty state. It is illegal to make 728 a state that has not been initialized with security parameters a 729 current state. The initial current state always specifies that no 730 encryption, compression, or MAC will be used. 732 The security parameters for a TLS Connection read and write state are 733 set by providing the following values: 735 connection end 736 Whether this entity is considered the "client" or the "server" in 737 this connection. 739 PRF algorithm 740 An algorithm used to generate keys from the master secret (see 741 Sections 5 and 6.3). 743 bulk encryption algorithm 744 An algorithm to be used for bulk encryption. This specification 745 includes the key size of this algorithm, whether it is a block, 746 stream, or AEAD cipher, the block size of the cipher (if 747 appropriate), and the lengths of explicit and implicit 748 initialization vectors (or nonces). 750 MAC algorithm 751 An algorithm to be used for message authentication. This 752 specification includes the size of the value returned by the MAC 753 algorithm. 755 compression algorithm 756 An algorithm to be used for data compression. This specification 757 must include all information the algorithm requires to do 758 compression. 760 master secret 761 A 48-byte secret shared between the two peers in the connection. 763 client random 764 A 32-byte value provided by the client. 766 server random 767 A 32-byte value provided by the server. 769 These parameters are defined in the presentation language as: 771 enum { server, client } ConnectionEnd; 773 enum { tls_prf_sha256 } PRFAlgorithm; 775 enum { null, rc4, 3des, aes } 776 BulkCipherAlgorithm; 778 enum { stream, block, aead } CipherType; 780 enum { null, hmac_md5, hmac_sha, hmac_sha256, hmac_sha384, 781 hmac_sha512} MACAlgorithm; 783 /* The use of "sha" above is historical and denotes SHA-1 */ 785 enum { null(0), (255) } CompressionMethod; 787 /* The algorithms specified in CompressionMethod, 788 BulkCipherAlgorithm, and MACAlgorithm may be added to. */ 790 struct { 791 ConnectionEnd entity; 792 PRFAlgorithm prf_algorithm; 793 BulkCipherAlgorithm bulk_cipher_algorithm; 794 CipherType cipher_type; 795 uint8 enc_key_length; 796 uint8 block_length; 797 uint8 fixed_iv_length; 798 uint8 record_iv_length; 799 MACAlgorithm mac_algorithm; 800 uint8 mac_length; 801 uint8 mac_key_length; 802 CompressionMethod compression_algorithm; 803 opaque master_secret[48]; 804 opaque client_random[32]; 805 opaque server_random[32]; 806 } SecurityParameters; 808 The record layer will use the security parameters to generate the 809 following six items (some of which are not required by all ciphers, 810 and are thus empty): 812 client write MAC key 813 server write MAC key 814 client write encryption key 815 server write encryption key 816 client write IV 817 server write IV 819 The client write parameters are used by the server when receiving and 820 processing records and vice-versa. The algorithm used for generating 821 these items from the security parameters is described in Section 6.3. 823 Once the security parameters have been set and the keys have been 824 generated, the connection states can be instantiated by making them 825 the current states. These current states MUST be updated for each 826 record processed. Each connection state includes the following 827 elements: 829 compression state 830 The current state of the compression algorithm. 832 cipher state 833 The current state of the encryption algorithm. This will consist 834 of the scheduled key for that connection. For stream ciphers, this 835 will also contain whatever state information is necessary to allow 836 the stream to continue to encrypt or decrypt data. 838 MAC key 839 The MAC key for this connection, as generated above. 841 sequence number 842 Each connection state contains a sequence number, which is 843 maintained separately for read and write states. The sequence 844 number MUST be set to zero whenever a connection state is made the 845 active state. Sequence numbers are of type uint64 and may not 846 exceed 2^64-1. Sequence numbers do not wrap. If a TLS 847 implementation would need to wrap a sequence number, it must 848 renegotiate instead. A sequence number is incremented after each 849 record: specifically, the first record transmitted under a 850 particular connection state MUST use sequence number 0. 852 6.2. Record layer 854 The TLS Record Layer receives uninterpreted data from higher layers 855 in non-empty blocks of arbitrary size. 857 6.2.1. Fragmentation 859 The record layer fragments information blocks into TLSPlaintext 860 records carrying data in chunks of 2^14 bytes or less. Client message 861 boundaries are not preserved in the record layer (i.e., multiple 862 client messages of the same ContentType MAY be coalesced into a 863 single TLSPlaintext record, or a single message MAY be fragmented 864 across several records). 866 struct { 867 uint8 major; 868 uint8 minor; 869 } ProtocolVersion; 871 enum { 872 change_cipher_spec(20), alert(21), handshake(22), 873 application_data(23), (255) 874 } ContentType; 876 struct { 877 ContentType type; 878 ProtocolVersion version; 879 uint16 length; 880 opaque fragment[TLSPlaintext.length]; 881 } TLSPlaintext; 883 type 884 The higher-level protocol used to process the enclosed fragment. 886 version 887 The version of the protocol being employed. This document 888 describes TLS Version 1.2, which uses the version { 3, 3 }. The 889 version value 3.3 is historical, deriving from the use of 3.1 for 890 TLS 1.0. (See Appendix A.1). Note that a client that supports 891 multiple versions of TLS may not know what version will be 892 employed before it receives the ServerHello. See Appendix E for 893 discussion about what record layer version number should be 894 employed for ClientHello. 896 length 897 The length (in bytes) of the following TLSPlaintext.fragment. The 898 length MUST NOT exceed 2^14. 900 fragment 901 The application data. This data is transparent and treated as an 902 independent block to be dealt with by the higher-level protocol 903 specified by the type field. 905 Implementations MUST NOT send zero-length fragments of Handshake, 906 Alert, or Change Cipher Spec content types. Zero-length fragments of 907 Application data MAY be sent as they are potentially useful as a 908 traffic analysis countermeasure. 910 Note: Data of different TLS Record layer content types MAY be 911 interleaved. Application data is generally of lower precedence for 912 transmission than other content types. However, records MUST be 913 delivered to the network in the same order as they are protected by 914 the record layer. Recipients MUST receive and process interleaved 915 application layer traffic during handshakes subsequent to the first 916 one on a connection. 918 6.2.2. Record Compression and Decompression 920 All records are compressed using the compression algorithm defined in 921 the current session state. There is always an active compression 922 algorithm; however, initially it is defined as 923 CompressionMethod.null. The compression algorithm translates a 924 TLSPlaintext structure into a TLSCompressed structure. Compression 925 functions are initialized with default state information whenever a 926 connection state is made active. 928 Compression must be lossless and may not increase the content length 929 by more than 1024 bytes. If the decompression function encounters a 930 TLSCompressed.fragment that would decompress to a length in excess of 931 2^14 bytes, it MUST report a fatal decompression failure error. 933 struct { 934 ContentType type; /* same as TLSPlaintext.type */ 935 ProtocolVersion version;/* same as TLSPlaintext.version */ 936 uint16 length; 937 opaque fragment[TLSCompressed.length]; 938 } TLSCompressed; 940 length 941 The length (in bytes) of the following TLSCompressed.fragment. 942 The length MUST NOT exceed 2^14 + 1024. 944 fragment 945 The compressed form of TLSPlaintext.fragment. 947 Note: A CompressionMethod.null operation is an identity operation; no 948 fields are altered. 950 Implementation note: Decompression functions are responsible for 951 ensuring that messages cannot cause internal buffer overflows. 953 6.2.3. Record Payload Protection 955 The encryption and MAC functions translate a TLSCompressed structure 956 into a TLSCiphertext. The decryption functions reverse the process. 957 The MAC of the record also includes a sequence number so that 958 missing, extra, or repeated messages are detectable. 960 struct { 961 ContentType type; 962 ProtocolVersion version; 963 uint16 length; 964 select (SecurityParameters.cipher_type) { 965 case stream: GenericStreamCipher; 966 case block: GenericBlockCipher; 967 case aead: GenericAEADCipher; 968 } fragment; 969 } TLSCiphertext; 971 type 972 The type field is identical to TLSCompressed.type. 974 version 975 The version field is identical to TLSCompressed.version. 977 length 978 The length (in bytes) of the following TLSCiphertext.fragment. 979 The length MUST NOT exceed 2^14 + 2048. 981 fragment 982 The encrypted form of TLSCompressed.fragment, with the MAC. 984 6.2.3.1. Null or Standard Stream Cipher 986 Stream ciphers (including BulkCipherAlgorithm.null, see Appendix A.6) 987 convert TLSCompressed.fragment structures to and from stream 988 TLSCiphertext.fragment structures. 990 stream-ciphered struct { 991 opaque content[TLSCompressed.length]; 992 opaque MAC[SecurityParameters.mac_length]; 993 } GenericStreamCipher; 995 The MAC is generated as: 997 MAC(MAC_write_key, seq_num + 998 TLSCompressed.type + 999 TLSCompressed.version + 1000 TLSCompressed.length + 1001 TLSCompressed.fragment); 1003 where "+" denotes concatenation. 1005 seq_num 1006 The sequence number for this record. 1008 MAC 1009 The MAC algorithm specified by SecurityParameters.mac_algorithm. 1011 Note that the MAC is computed before encryption. The stream cipher 1012 encrypts the entire block, including the MAC. For stream ciphers that 1013 do not use a synchronization vector (such as RC4), the stream cipher 1014 state from the end of one record is simply used on the subsequent 1015 packet. If the cipher suite is TLS_NULL_WITH_NULL_NULL, encryption 1016 consists of the identity operation (i.e., the data is not encrypted, 1017 and the MAC size is zero, implying that no MAC is used). 1018 TLSCiphertext.length is TLSCompressed.length plus 1019 SecurityParameters.mac_length. 1021 6.2.3.2. CBC Block Cipher 1023 For block ciphers (such as 3DES, or AES), the encryption and MAC 1024 functions convert TLSCompressed.fragment structures to and from block 1025 TLSCiphertext.fragment structures. 1027 struct { 1028 opaque IV[SecurityParameters.record_iv_length]; 1029 block-ciphered struct { 1030 opaque content[TLSCompressed.length]; 1031 opaque MAC[SecurityParameters.mac_length]; 1032 uint8 padding[GenericBlockCipher.padding_length]; 1033 uint8 padding_length; 1034 }; 1035 } GenericBlockCipher; 1037 The MAC is generated as described in Section 6.2.3.1. 1039 IV 1040 The Initialization Vector (IV) SHOULD be chosen at random, and 1041 MUST be unpredictable. Note that in versions of TLS prior to 1.1, 1042 there was no IV field, and the last ciphertext block of the 1043 previous record (the "CBC residue") was used as the IV. This was 1044 changed to prevent the attacks described in [CBCATT]. For block 1045 ciphers, the IV length is of length 1046 SecurityParameters.record_iv_length which is equal to the 1047 SecurityParameters.block_size. 1049 padding 1050 Padding that is added to force the length of the plaintext to be 1051 an integral multiple of the block cipher's block length. The 1052 padding MAY be any length up to 255 bytes, as long as it results 1053 in the TLSCiphertext.length being an integral multiple of the 1054 block length. Lengths longer than necessary might be desirable to 1055 frustrate attacks on a protocol that are based on analysis of the 1056 lengths of exchanged messages. Each uint8 in the padding data 1057 vector MUST be filled with the padding length value. The receiver 1058 MUST check this padding and MUST use the bad_record_mac alert to 1059 indicate padding errors. 1061 padding_length 1062 The padding length MUST be such that the total size of the 1063 GenericBlockCipher structure is a multiple of the cipher's block 1064 length. Legal values range from zero to 255, inclusive. This 1065 length specifies the length of the padding field exclusive of the 1066 padding_length field itself. 1068 The encrypted data length (TLSCiphertext.length) is one more than the 1069 sum of SecurityParameters.block_length, TLSCompressed.length, 1070 SecurityParameters.mac_length, and padding_length. 1072 Example: If the block length is 8 bytes, the content length 1073 (TLSCompressed.length) is 61 bytes, and the MAC length is 20 bytes, 1074 then the length before padding is 82 bytes (this does not include the 1075 IV. Thus, the padding length modulo 8 must be equal to 6 in order to 1076 make the total length an even multiple of 8 bytes (the block length). 1077 The padding length can be 6, 14, 22, and so on, through 254. If the 1078 padding length were the minimum necessary, 6, the padding would be 6 1079 bytes, each containing the value 6. Thus, the last 8 octets of the 1080 GenericBlockCipher before block encryption would be xx 06 06 06 06 06 1081 06 06, where xx is the last octet of the MAC. 1083 Note: With block ciphers in CBC mode (Cipher Block Chaining), it is 1084 critical that the entire plaintext of the record be known before any 1085 ciphertext is transmitted. Otherwise, it is possible for the attacker 1086 to mount the attack described in [CBCATT]. 1088 Implementation Note: Canvel et al. [CBCTIME] have demonstrated a 1089 timing attack on CBC padding based on the time required to compute 1090 the MAC. In order to defend against this attack, implementations MUST 1091 ensure that record processing time is essentially the same whether or 1092 not the padding is correct. In general, the best way to do this is 1093 to compute the MAC even if the padding is incorrect, and only then 1094 reject the packet. For instance, if the pad appears to be incorrect, 1095 the implementation might assume a zero-length pad and then compute 1096 the MAC. This leaves a small timing channel, since MAC performance 1097 depends to some extent on the size of the data fragment, but it is 1098 not believed to be large enough to be exploitable, due to the large 1099 block size of existing MACs and the small size of the timing signal. 1101 6.2.3.3. AEAD ciphers 1103 For AEAD [AEAD] ciphers (such as [CCM] or [GCM]) the AEAD function 1104 converts TLSCompressed.fragment structures to and from AEAD 1105 TLSCiphertext.fragment structures. 1107 struct { 1108 opaque nonce_explicit[SecurityParameters.record_iv_length]; 1109 aead-ciphered struct { 1110 opaque content[TLSCompressed.length]; 1111 }; 1112 } GenericAEADCipher; 1114 AEAD ciphers take as input a single key, a nonce, a plaintext, and 1115 "additional data" to be included in the authentication check, as 1116 described in Section 2.1 of [AEAD]. The key is either the 1117 client_write_key or the server_write_key. No MAC key is used. 1119 Each AEAD cipher suite MUST specify how the nonce supplied to the 1120 AEAD operation is constructed, and what is the length of the 1121 GenericAEADCipher.nonce_explicit part. In many cases, it is 1122 appropriate to use the partially implicit nonce technique described 1123 in Section 3.2.1 of [AEAD]; with record_iv_length being the length of 1124 the explicit part. In this case, the implicit part SHOULD be derived 1125 from key_block as client_write_iv and server_write_iv (as described 1126 in Section 6.3), and the explicit part is included in 1127 GenericAEAEDCipher.nonce_explicit. 1129 The plaintext is the TLSCompressed.fragment. 1131 The additional authenticated data, which we denote as 1132 additional_data, is defined as follows: 1134 additional_data = seq_num + TLSCompressed.type + 1135 TLSCompressed.version + TLSCompressed.length; 1137 Where "+" denotes concatenation. 1139 The aead_output consists of the ciphertext output by the AEAD 1140 encryption operation. The length will generally be larger than 1141 TLSCompressed.length, but by an amount that varies with the AEAD 1142 cipher. Since the ciphers might incorporate padding, the amount of 1143 overhead could vary with different TLSCompressed.length values. Each 1144 AEAD cipher MUST NOT produce an expansion of greater than 1024 bytes. 1146 Symbolically, 1148 AEADEncrypted = AEAD-Encrypt(key, nonce, plaintext, 1149 additional_data) 1151 In order to decrypt and verify, the cipher takes as input the key, 1152 nonce, the "additional_data", and the AEADEncrypted value. The output 1153 is either the plaintext or an error indicating that the decryption 1154 failed. There is no separate integrity check. I.e., 1156 TLSCompressed.fragment = AEAD-Decrypt(write_key, nonce, 1157 AEADEncrypted, 1158 additional_data) 1160 If the decryption fails, a fatal bad_record_mac alert MUST be 1161 generated. 1163 6.3. Key Calculation 1165 The Record Protocol requires an algorithm to generates keys required 1166 by the current connection state (see Appendix A.6) from the security 1167 parameters provided by the handshake protocol. 1169 The master secret is expanded into a sequence of secure bytes, which 1170 is then split to a client write MAC key, a server write MAC key, a 1171 client write encryption key, and a server write encryption key. Each 1172 of these is generated from the byte sequence in that order. Unused 1173 values are empty. Some AEAD ciphers may additionally require a 1174 client write IV and a server write IV (see Section 6.2.3.3). 1176 When keys and MAC keys are generated, the master secret is used as an 1177 entropy source. 1179 To generate the key material, compute 1181 key_block = PRF(SecurityParameters.master_secret, 1182 "key expansion", 1183 SecurityParameters.server_random + 1184 SecurityParameters.client_random); 1186 until enough output has been generated. Then the key_block is 1187 partitioned as follows: 1189 client_write_MAC_key[SecurityParameters.mac_key_length] 1190 server_write_MAC_key[SecurityParameters.mac_key_length] 1191 client_write_key[SecurityParameters.enc_key_length] 1192 server_write_key[SecurityParameters.enc_key_length] 1193 client_write_IV[SecurityParameters.fixed_iv_length] 1194 server_write_IV[SecurityParameters.fixed_iv_length] 1196 Currently, the client_write_IV and server_write_IV are only generated 1197 for implicit nonce techniques as described in Section 3.2.1 of 1198 [AEAD]. 1200 Implementation note: The currently defined cipher suite which 1201 requires the most material is AES_256_CBC_SHA256. It requires 2 x 32 1202 byte keys and 2 x 32 byte MAC keys, for a total 128 bytes of key 1203 material. 1205 7. The TLS Handshaking Protocols 1207 TLS has three subprotocols that are used to allow peers to agree upon 1208 security parameters for the record layer, to authenticate themselves, 1209 to instantiate negotiated security parameters, and to report error 1210 conditions to each other. 1212 The Handshake Protocol is responsible for negotiating a session, 1213 which consists of the following items: 1215 session identifier 1216 An arbitrary byte sequence chosen by the server to identify an 1217 active or resumable session state. 1219 peer certificate 1220 X509v3 [PKIX] certificate of the peer. This element of the state 1221 may be null. 1223 compression method 1224 The algorithm used to compress data prior to encryption. 1226 cipher spec 1227 Specifies the bulk data encryption algorithm (such as null, DES, 1228 etc.) and a MAC algorithm (such as MD5 or SHA). It also defines 1229 cryptographic attributes such as the mac_length. (See Appendix A.6 1230 for formal definition.) 1232 master secret 1233 48-byte secret shared between the client and server. 1235 is resumable 1236 A flag indicating whether the session can be used to initiate new 1237 connections. 1239 These items are then used to create security parameters for use by 1240 the Record Layer when protecting application data. Many connections 1241 can be instantiated using the same session through the resumption 1242 feature of the TLS Handshake Protocol. 1244 7.1. Change Cipher Spec Protocol 1246 The change cipher spec protocol exists to signal transitions in 1247 ciphering strategies. The protocol consists of a single message, 1248 which is encrypted and compressed under the current (not the pending) 1249 connection state. The message consists of a single byte of value 1. 1251 struct { 1252 enum { change_cipher_spec(1), (255) } type; 1253 } ChangeCipherSpec; 1255 The change cipher spec message is sent by both the client and the 1256 server to notify the receiving party that subsequent records will be 1257 protected under the newly negotiated CipherSpec and keys. Reception 1258 of this message causes the receiver to instruct the Record Layer to 1259 immediately copy the read pending state into the read current state. 1260 Immediately after sending this message, the sender MUST instruct the 1261 record layer to make the write pending state the write active state. 1262 (See Section 6.1.) The change cipher spec message is sent during the 1263 handshake after the security parameters have been agreed upon, but 1264 before the verifying finished message is sent. 1266 Note: If a rehandshake occurs while data is flowing on a connection, 1267 the communicating parties may continue to send data using the old 1268 CipherSpec. However, once the ChangeCipherSpec has been sent, the new 1269 CipherSpec MUST be used. The first side to send the ChangeCipherSpec 1270 does not know that the other side has finished computing the new 1271 keying material (e.g., if it has to perform a time consuming public 1272 key operation). Thus, a small window of time, during which the 1273 recipient must buffer the data, MAY exist. In practice, with modern 1274 machines this interval is likely to be fairly short. 1276 7.2. Alert Protocol 1278 One of the content types supported by the TLS Record layer is the 1279 alert type. Alert messages convey the severity of the message and a 1280 description of the alert. Alert messages with a level of fatal result 1281 in the immediate termination of the connection. In this case, other 1282 connections corresponding to the session may continue, but the 1283 session identifier MUST be invalidated, preventing the failed session 1284 from being used to establish new connections. Like other messages, 1285 alert messages are encrypted and compressed, as specified by the 1286 current connection state. 1288 enum { warning(1), fatal(2), (255) } AlertLevel; 1289 enum { 1290 close_notify(0), 1291 unexpected_message(10), 1292 bad_record_mac(20), 1293 decryption_failed_RESERVED(21), 1294 record_overflow(22), 1295 decompression_failure(30), 1296 handshake_failure(40), 1297 no_certificate_RESERVED(41), 1298 bad_certificate(42), 1299 unsupported_certificate(43), 1300 certificate_revoked(44), 1301 certificate_expired(45), 1302 certificate_unknown(46), 1303 illegal_parameter(47), 1304 unknown_ca(48), 1305 access_denied(49), 1306 decode_error(50), 1307 decrypt_error(51), 1308 export_restriction_RESERVED(60), 1309 protocol_version(70), 1310 insufficient_security(71), 1311 internal_error(80), 1312 user_canceled(90), 1313 no_renegotiation(100), 1314 unsupported_extension(110), 1315 (255) 1316 } AlertDescription; 1318 struct { 1319 AlertLevel level; 1320 AlertDescription description; 1321 } Alert; 1323 7.2.1. Closure Alerts 1325 The client and the server must share knowledge that the connection is 1326 ending in order to avoid a truncation attack. Either party may 1327 initiate the exchange of closing messages. 1329 close_notify 1330 This message notifies the recipient that the sender will not send 1331 any more messages on this connection. Note that as of TLS 1.1, 1332 failure to properly close a connection no longer requires that a 1333 session not be resumed. This is a change from TLS 1.0 to conform 1334 with widespread implementation practice. 1336 Either party may initiate a close by sending a close_notify alert. 1338 Any data received after a closure alert is ignored. 1340 Unless some other fatal alert has been transmitted, each party is 1341 required to send a close_notify alert before closing the write side 1342 of the connection. The other party MUST respond with a close_notify 1343 alert of its own and close down the connection immediately, 1344 discarding any pending writes. It is not required for the initiator 1345 of the close to wait for the responding close_notify alert before 1346 closing the read side of the connection. 1348 If the application protocol using TLS provides that any data may be 1349 carried over the underlying transport after the TLS connection is 1350 closed, the TLS implementation must receive the responding 1351 close_notify alert before indicating to the application layer that 1352 the TLS connection has ended. If the application protocol will not 1353 transfer any additional data, but will only close the underlying 1354 transport connection, then the implementation MAY choose to close the 1355 transport without waiting for the responding close_notify. No part of 1356 this standard should be taken to dictate the manner in which a usage 1357 profile for TLS manages its data transport, including when 1358 connections are opened or closed. 1360 Note: It is assumed that closing a connection reliably delivers 1361 pending data before destroying the transport. 1363 7.2.2. Error Alerts 1365 Error handling in the TLS Handshake protocol is very simple. When an 1366 error is detected, the detecting party sends a message to the other 1367 party. Upon transmission or receipt of a fatal alert message, both 1368 parties immediately close the connection. Servers and clients MUST 1369 forget any session-identifiers, keys, and secrets associated with a 1370 failed connection. Thus, any connection terminated with a fatal alert 1371 MUST NOT be resumed. 1373 Whenever an implementation encounters a condition which is defined as 1374 a fatal alert, it MUST send the appropriate alert prior to closing 1375 the connection. For all errors where an alert level is not explicitly 1376 specified, the sending party MAY determine at its discretion whether 1377 to treat this as a fatal error or not. If the implementation chooses 1378 to send an alert but intends to close the connection immediately 1379 afterwards, it MUST send that alert at the fatal alert level. 1381 If an alert with a level of warning is sent and received, generally 1382 the connection can continue normally. If the receiving party decides 1383 not to proceed with the connection (e.g., after having received a 1384 no_renegotiation alert that it is not willing to accept), it SHOULD 1385 send a fatal alert to terminate the connection. Given this, the 1386 sending party cannot, in general, know how the receiving party will 1387 behave. Therefore, warning alerts are not very useful when the 1388 sending party wants to continue the connection, and thus are 1389 sometimes omitted. For example, if a peer decides to accept an 1390 expired certificate (perhaps after confirming this with the user) and 1391 wants to continue the connection, it would not generally send a 1392 certificate_expired alert. 1394 The following error alerts are defined: 1396 unexpected_message 1397 An inappropriate message was received. This alert is always fatal 1398 and should never be observed in communication between proper 1399 implementations. 1401 bad_record_mac 1402 This alert is returned if a record is received with an incorrect 1403 MAC. This alert also MUST be returned if an alert is sent because 1404 a TLSCiphertext decrypted in an invalid way: either it wasn't an 1405 even multiple of the block length, or its padding values, when 1406 checked, weren't correct. This message is always fatal and should 1407 never be observed in communication between proper implementations 1408 (except when messages were corrupted in the network). 1410 decryption_failed_RESERVED 1411 This alert was used in some earlier versions of TLS, and may have 1412 permitted certain attacks against the CBC mode [CBCATT]. It MUST 1413 NOT be sent by compliant implementations. 1415 record_overflow 1416 A TLSCiphertext record was received that had a length more than 1417 2^14+2048 bytes, or a record decrypted to a TLSCompressed record 1418 with more than 2^14+1024 bytes. This message is always fatal and 1419 should never be observed in communication between proper 1420 implementations (except when messages were corrupted in the 1421 network). 1423 decompression_failure 1424 The decompression function received improper input (e.g., data 1425 that would expand to excessive length). This message is always 1426 fatal and should never be observed in communication between proper 1427 implementations. 1429 handshake_failure 1430 Reception of a handshake_failure alert message indicates that the 1431 sender was unable to negotiate an acceptable set of security 1432 parameters given the options available. This is a fatal error. 1434 no_certificate_RESERVED 1435 This alert was used in SSLv3 but not any version of TLS. It MUST 1436 NOT be sent by compliant implementations. 1438 bad_certificate 1439 A certificate was corrupt, contained signatures that did not 1440 verify correctly, etc. 1442 unsupported_certificate 1443 A certificate was of an unsupported type. 1445 certificate_revoked 1446 A certificate was revoked by its signer. 1448 certificate_expired 1449 A certificate has expired or is not currently valid. 1451 certificate_unknown 1452 Some other (unspecified) issue arose in processing the 1453 certificate, rendering it unacceptable. 1455 illegal_parameter 1456 A field in the handshake was out of range or inconsistent with 1457 other fields. This message is always fatal. 1459 unknown_ca 1460 A valid certificate chain or partial chain was received, but the 1461 certificate was not accepted because the CA certificate could not 1462 be located or couldn't be matched with a known, trusted CA. This 1463 message is always fatal. 1465 access_denied 1466 A valid certificate was received, but when access control was 1467 applied, the sender decided not to proceed with negotiation. This 1468 message is always fatal. 1470 decode_error 1471 A message could not be decoded because some field was out of the 1472 specified range or the length of the message was incorrect. This 1473 message is always fatal and should never be observed in 1474 communication between proper implementations (except when messages 1475 were corrupted in the network). 1477 decrypt_error 1478 A handshake cryptographic operation failed, including being unable 1479 to correctly verify a signature or validate a finished message. 1480 This message is always fatal. 1482 export_restriction_RESERVED 1483 This alert was used in some earlier versions of TLS. It MUST NOT 1484 be sent by compliant implementations. 1486 protocol_version 1487 The protocol version the client has attempted to negotiate is 1488 recognized but not supported. (For example, old protocol versions 1489 might be avoided for security reasons). This message is always 1490 fatal. 1492 insufficient_security 1493 Returned instead of handshake_failure when a negotiation has 1494 failed specifically because the server requires ciphers more 1495 secure than those supported by the client. This message is always 1496 fatal. 1498 internal_error 1499 An internal error unrelated to the peer or the correctness of the 1500 protocol (such as a memory allocation failure) makes it impossible 1501 to continue. This message is always fatal. 1503 user_canceled 1504 This handshake is being canceled for some reason unrelated to a 1505 protocol failure. If the user cancels an operation after the 1506 handshake is complete, just closing the connection by sending a 1507 close_notify is more appropriate. This alert should be followed by 1508 a close_notify. This message is generally a warning. 1510 no_renegotiation 1511 Sent by the client in response to a hello request or by the server 1512 in response to a client hello after initial handshaking. Either 1513 of these would normally lead to renegotiation; when that is not 1514 appropriate, the recipient should respond with this alert. At 1515 that point, the original requester can decide whether to proceed 1516 with the connection. One case where this would be appropriate is 1517 where a server has spawned a process to satisfy a request; the 1518 process might receive security parameters (key length, 1519 authentication, etc.) at startup and it might be difficult to 1520 communicate changes to these parameters after that point. This 1521 message is always a warning. 1523 unsupported_extension 1524 sent by clients that receive an extended server hello containing 1525 an extension that they did not put in the corresponding client 1526 hello. This message is always fatal. 1528 New Alert values are assigned by IANA as described in Section 12. 1530 7.3. Handshake Protocol Overview 1532 The cryptographic parameters of the session state are produced by the 1533 TLS Handshake Protocol, which operates on top of the TLS Record 1534 Layer. When a TLS client and server first start communicating, they 1535 agree on a protocol version, select cryptographic algorithms, 1536 optionally authenticate each other, and use public-key encryption 1537 techniques to generate shared secrets. 1539 The TLS Handshake Protocol involves the following steps: 1541 - Exchange hello messages to agree on algorithms, exchange random 1542 values, and check for session resumption. 1544 - Exchange the necessary cryptographic parameters to allow the 1545 client and server to agree on a premaster secret. 1547 - Exchange certificates and cryptographic information to allow the 1548 client and server to authenticate themselves. 1550 - Generate a master secret from the premaster secret and exchanged 1551 random values. 1553 - Provide security parameters to the record layer. 1555 - Allow the client and server to verify that their peer has 1556 calculated the same security parameters and that the handshake 1557 occurred without tampering by an attacker. 1559 Note that higher layers should not be overly reliant on whether TLS 1560 always negotiates the strongest possible connection between two 1561 peers. There are a number of ways in which a man in the middle 1562 attacker can attempt to make two entities drop down to the least 1563 secure method they support. The protocol has been designed to 1564 minimize this risk, but there are still attacks available: for 1565 example, an attacker could block access to the port a secure service 1566 runs on, or attempt to get the peers to negotiate an unauthenticated 1567 connection. The fundamental rule is that higher levels must be 1568 cognizant of what their security requirements are and never transmit 1569 information over a channel less secure than what they require. The 1570 TLS protocol is secure in that any cipher suite offers its promised 1571 level of security: if you negotiate 3DES with a 1024 bit RSA key 1572 exchange with a host whose certificate you have verified, you can 1573 expect to be that secure. 1575 These goals are achieved by the handshake protocol, which can be 1576 summarized as follows: The client sends a client hello message to 1577 which the server must respond with a server hello message, or else a 1578 fatal error will occur and the connection will fail. The client hello 1579 and server hello are used to establish security enhancement 1580 capabilities between client and server. The client hello and server 1581 hello establish the following attributes: Protocol Version, Session 1582 ID, Cipher Suite, and Compression Method. Additionally, two random 1583 values are generated and exchanged: ClientHello.random and 1584 ServerHello.random. 1586 The actual key exchange uses up to four messages: the server 1587 certificate, the server key exchange, the client certificate, and the 1588 client key exchange. New key exchange methods can be created by 1589 specifying a format for these messages and by defining the use of the 1590 messages to allow the client and server to agree upon a shared 1591 secret. This secret MUST be quite long; currently defined key 1592 exchange methods exchange secrets that range from 46 bytes upwards. 1594 Following the hello messages, the server will send its certificate, 1595 if it is to be authenticated. Additionally, a server key exchange 1596 message may be sent, if it is required (e.g., if their server has no 1597 certificate, or if its certificate is for signing only). If the 1598 server is authenticated, it may request a certificate from the 1599 client, if that is appropriate to the cipher suite selected. Next, 1600 the server will send the server hello done message, indicating that 1601 the hello-message phase of the handshake is complete. The server will 1602 then wait for a client response. If the server has sent a certificate 1603 request message, the client MUST send the certificate message. The 1604 client key exchange message is now sent, and the content of that 1605 message will depend on the public key algorithm selected between the 1606 client hello and the server hello. If the client has sent a 1607 certificate with signing ability, a digitally-signed certificate 1608 verify message is sent to explicitly verify possession of the private 1609 key in the certificate. 1611 At this point, a change cipher spec message is sent by the client, 1612 and the client copies the pending Cipher Spec into the current Cipher 1613 Spec. The client then immediately sends the finished message under 1614 the new algorithms, keys, and secrets. In response, the server will 1615 send its own change cipher spec message, transfer the pending to the 1616 current Cipher Spec, and send its finished message under the new 1617 Cipher Spec. At this point, the handshake is complete, and the client 1618 and server may begin to exchange application layer data. (See flow 1619 chart below.) Application data MUST NOT be sent prior to the 1620 completion of the first handshake (before a cipher suite other than 1621 TLS_NULL_WITH_NULL_NULL is established). 1623 Client Server 1625 ClientHello --------> 1626 ServerHello 1627 Certificate* 1628 ServerKeyExchange* 1629 CertificateRequest* 1630 <-------- ServerHelloDone 1631 Certificate* 1632 ClientKeyExchange 1633 CertificateVerify* 1634 [ChangeCipherSpec] 1635 Finished --------> 1636 [ChangeCipherSpec] 1637 <-------- Finished 1638 Application Data <-------> Application Data 1640 Fig. 1. Message flow for a full handshake 1642 * Indicates optional or situation-dependent messages that are not 1643 always sent. 1645 Note: To help avoid pipeline stalls, ChangeCipherSpec is an 1646 independent TLS Protocol content type, and is not actually a TLS 1647 handshake message. 1649 When the client and server decide to resume a previous session or 1650 duplicate an existing session (instead of negotiating new security 1651 parameters), the message flow is as follows: 1653 The client sends a ClientHello using the Session ID of the session to 1654 be resumed. The server then checks its session cache for a match. If 1655 a match is found, and the server is willing to re-establish the 1656 connection under the specified session state, it will send a 1657 ServerHello with the same Session ID value. At this point, both 1658 client and server MUST send change cipher spec messages and proceed 1659 directly to finished messages. Once the re-establishment is complete, 1660 the client and server MAY begin to exchange application layer data. 1661 (See flow chart below.) If a Session ID match is not found, the 1662 server generates a new session ID and the TLS client and server 1663 perform a full handshake. 1665 Client Server 1667 ClientHello --------> 1668 ServerHello 1669 [ChangeCipherSpec] 1670 <-------- Finished 1671 [ChangeCipherSpec] 1672 Finished --------> 1673 Application Data <-------> Application Data 1674 Fig. 2. Message flow for an abbreviated handshake 1676 The contents and significance of each message will be presented in 1677 detail in the following sections. 1679 7.4. Handshake Protocol 1681 The TLS Handshake Protocol is one of the defined higher-level clients 1682 of the TLS Record Protocol. This protocol is used to negotiate the 1683 secure attributes of a session. Handshake messages are supplied to 1684 the TLS Record Layer, where they are encapsulated within one or more 1685 TLSPlaintext structures, which are processed and transmitted as 1686 specified by the current active session state. 1688 enum { 1689 hello_request(0), client_hello(1), server_hello(2), 1690 certificate(11), server_key_exchange (12), 1691 certificate_request(13), server_hello_done(14), 1692 certificate_verify(15), client_key_exchange(16), 1693 finished(20), (255) 1694 } HandshakeType; 1696 struct { 1697 HandshakeType msg_type; /* handshake type */ 1698 uint24 length; /* bytes in message */ 1699 select (HandshakeType) { 1700 case hello_request: HelloRequest; 1701 case client_hello: ClientHello; 1702 case server_hello: ServerHello; 1703 case certificate: Certificate; 1704 case server_key_exchange: ServerKeyExchange; 1705 case certificate_request: CertificateRequest; 1706 case server_hello_done: ServerHelloDone; 1707 case certificate_verify: CertificateVerify; 1708 case client_key_exchange: ClientKeyExchange; 1709 case finished: Finished; 1710 } body; 1711 } Handshake; 1713 The handshake protocol messages are presented below in the order they 1714 MUST be sent; sending handshake messages in an unexpected order 1715 results in a fatal error. Unneeded handshake messages can be omitted, 1716 however. Note one exception to the ordering: the Certificate message 1717 is used twice in the handshake (from server to client, then from 1718 client to server), but described only in its first position. The one 1719 message that is not bound by these ordering rules is the Hello 1720 Request message, which can be sent at any time, but which SHOULD be 1721 ignored by the client if it arrives in the middle of a handshake. 1723 New Handshake message types are assigned by IANA as described in 1724 Section 12. 1726 7.4.1. Hello Messages 1728 The hello phase messages are used to exchange security enhancement 1729 capabilities between the client and server. When a new session 1730 begins, the Record Layer's connection state encryption, hash, and 1731 compression algorithms are initialized to null. The current 1732 connection state is used for renegotiation messages. 1734 7.4.1.1. Hello Request 1736 When this message will be sent: 1738 The hello request message MAY be sent by the server at any time. 1740 Meaning of this message: 1742 Hello request is a simple notification that the client should 1743 begin the negotiation process anew by sending a client hello 1744 message when convenient. This message is not intended to establish 1745 which side is the client or server but merely to initiate a new 1746 negotiation. Servers SHOULD NOT send a HelloRequest immediately 1747 upon the client's initial connection. It is the client's job to 1748 send a ClientHello at that time. 1750 This message will be ignored by the client if the client is 1751 currently negotiating a session. This message may be ignored by 1752 the client if it does not wish to renegotiate a session, or the 1753 client may, if it wishes, respond with a no_renegotiation alert. 1754 Since handshake messages are intended to have transmission 1755 precedence over application data, it is expected that the 1756 negotiation will begin before no more than a few records are 1757 received from the client. If the server sends a hello request but 1758 does not receive a client hello in response, it may close the 1759 connection with a fatal alert. 1761 After sending a hello request, servers SHOULD NOT repeat the 1762 request until the subsequent handshake negotiation is complete. 1764 Structure of this message: 1766 struct { } HelloRequest; 1768 Note: This message MUST NOT be included in the message hashes that 1769 are maintained throughout the handshake and used in the finished 1770 messages and the certificate verify message. 1772 7.4.1.2. Client Hello 1774 When this message will be sent: 1776 When a client first connects to a server it is required to send 1777 the client hello as its first message. The client can also send a 1778 client hello in response to a hello request or on its own 1779 initiative in order to renegotiate the security parameters in an 1780 existing connection. 1782 Structure of this message: 1784 The client hello message includes a random structure, which is 1785 used later in the protocol. 1787 struct { 1788 uint32 gmt_unix_time; 1789 opaque random_bytes[28]; 1790 } Random; 1792 gmt_unix_time 1793 The current time and date in standard UNIX 32-bit format 1794 (seconds since the midnight starting Jan 1, 1970, GMT, ignoring 1795 leap seconds) according to the sender's internal clock. Clocks 1796 are not required to be set correctly by the basic TLS Protocol; 1797 higher-level or application protocols may define additional 1798 requirements. 1800 random_bytes 1801 28 bytes generated by a secure random number generator. 1803 The client hello message includes a variable-length session 1804 identifier. If not empty, the value identifies a session between the 1805 same client and server whose security parameters the client wishes to 1806 reuse. The session identifier MAY be from an earlier connection, this 1807 connection, or from another currently active connection. The second 1808 option is useful if the client only wishes to update the random 1809 structures and derived values of a connection, and the third option 1810 makes it possible to establish several independent secure connections 1811 without repeating the full handshake protocol. These independent 1812 connections may occur sequentially or simultaneously; a SessionID 1813 becomes valid when the handshake negotiating it completes with the 1814 exchange of Finished messages and persists until it is removed due to 1815 aging or because a fatal error was encountered on a connection 1816 associated with the session. The actual contents of the SessionID are 1817 defined by the server. 1819 opaque SessionID<0..32>; 1821 Warning: Because the SessionID is transmitted without encryption or 1822 immediate MAC protection, servers MUST NOT place confidential 1823 information in session identifiers or let the contents of fake 1824 session identifiers cause any breach of security. (Note that the 1825 content of the handshake as a whole, including the SessionID, is 1826 protected by the Finished messages exchanged at the end of the 1827 handshake.) 1829 The cipher suite list, passed from the client to the server in the 1830 client hello message, contains the combinations of cryptographic 1831 algorithms supported by the client in order of the client's 1832 preference (favorite choice first). Each cipher suite defines a key 1833 exchange algorithm, a bulk encryption algorithm (including secret key 1834 length), a MAC algorithm, and a PRF. The server will select a cipher 1835 suite or, if no acceptable choices are presented, return a handshake 1836 failure alert and close the connection. If the list contains cipher 1837 suites the server does not recognize, support, or wish to use, the 1838 server MUST ignore those cipher suites, and process the remaining 1839 ones as usual. 1841 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 1843 The client hello includes a list of compression algorithms supported 1844 by the client, ordered according to the client's preference. 1846 enum { null(0), (255) } CompressionMethod; 1848 struct { 1849 ProtocolVersion client_version; 1850 Random random; 1851 SessionID session_id; 1852 CipherSuite cipher_suites<2..2^16-2>; 1853 CompressionMethod compression_methods<1..2^8-1>; 1854 select (extensions_present) { 1855 case false: 1856 struct {}; 1857 case true: 1858 Extension extensions<0..2^16-1>; 1859 }; 1860 } ClientHello; 1862 TLS allows extensions to follow the compression_methods field in an 1863 extensions block. The presence of extensions can be detected by 1864 determining whether there are bytes following the compression_methods 1865 at the end of the ClientHello. Note that this method of detecting 1866 optional data differs from the normal TLS method of having a 1867 variable-length field but is used for compatibility with TLS before 1868 extensions were defined. 1870 client_version 1871 The version of the TLS protocol by which the client wishes to 1872 communicate during this session. This SHOULD be the latest 1873 (highest valued) version supported by the client. For this version 1874 of the specification, the version will be 3.3 (See Appendix E for 1875 details about backward compatibility). 1877 random 1878 A client-generated random structure. 1880 session_id 1881 The ID of a session the client wishes to use for this connection. 1882 This field is empty if no session_id is available, or it the 1883 client wishes to generate new security parameters. 1885 cipher_suites 1886 This is a list of the cryptographic options supported by the 1887 client, with the client's first preference first. If the 1888 session_id field is not empty (implying a session resumption 1889 request) this vector MUST include at least the cipher_suite from 1890 that session. Values are defined in Appendix A.5. 1892 compression_methods 1893 This is a list of the compression methods supported by the client, 1894 sorted by client preference. If the session_id field is not empty 1895 (implying a session resumption request) it MUST include the 1896 compression_method from that session. This vector MUST contain, 1897 and all implementations MUST support, CompressionMethod.null. 1898 Thus, a client and server will always be able to agree on a 1899 compression method. 1901 extensions 1902 Clients MAY request extended functionality from servers by sending 1903 data in the extensions Here the new "extensions" field contains a 1904 list of extensions. The actual "Extension" format is defined in 1905 Section 7.4.1.4. 1907 In the event that a client requests additional functionality using 1908 extensions, and this functionality is not supplied by the server, the 1909 client MAY abort the handshake. A server MUST accept client hello 1910 messages both with and without the extensions field, and (as for all 1911 other messages) MUST check that the amount of data in the message 1912 precisely matches one of these formats; if not, then it MUST send a 1913 fatal "decode_error" alert. 1915 After sending the client hello message, the client waits for a server 1916 hello message. Any other handshake message returned by the server 1917 except for a hello request is treated as a fatal error. 1919 7.4.1.3. Server Hello 1921 When this message will be sent: 1923 The server will send this message in response to a client hello 1924 message when it was able to find an acceptable set of algorithms. 1925 If it cannot find such a match, it will respond with a handshake 1926 failure alert. 1928 Structure of this message: 1930 struct { 1931 ProtocolVersion server_version; 1932 Random random; 1933 SessionID session_id; 1934 CipherSuite cipher_suite; 1935 CompressionMethod compression_method; 1936 select (extensions_present) { 1937 case false: 1938 struct {}; 1939 case true: 1940 Extension extensions<0..2^16-1>; 1941 }; 1942 } ServerHello; 1944 The presence of extensions can be detected by determining whether 1945 there are bytes following the compression_method field at the end of 1946 the ServerHello. 1948 server_version 1949 This field will contain the lower of that suggested by the client 1950 in the client hello and the highest supported by the server. For 1951 this version of the specification, the version is 3.3. (See 1952 Appendix E for details about backward compatibility.) 1954 random 1955 This structure is generated by the server and MUST be 1956 independently generated from the ClientHello.random. 1958 session_id 1959 This is the identity of the session corresponding to this 1960 connection. If the ClientHello.session_id was non-empty, the 1961 server will look in its session cache for a match. If a match is 1962 found and the server is willing to establish the new connection 1963 using the specified session state, the server will respond with 1964 the same value as was supplied by the client. This indicates a 1965 resumed session and dictates that the parties must proceed 1966 directly to the finished messages. Otherwise this field will 1967 contain a different value identifying the new session. The server 1968 may return an empty session_id to indicate that the session will 1969 not be cached and therefore cannot be resumed. If a session is 1970 resumed, it must be resumed using the same cipher suite it was 1971 originally negotiated with. Note that there is no requirement that 1972 the server resume any session even if it had formerly provided a 1973 session_id. Client MUST be prepared to do a full negotiation -- 1974 including negotiating new cipher suites -- during any handshake. 1976 cipher_suite 1977 The single cipher suite selected by the server from the list in 1978 ClientHello.cipher_suites. For resumed sessions, this field is the 1979 value from the state of the session being resumed. 1981 compression_method 1982 The single compression algorithm selected by the server from the 1983 list in ClientHello.compression_methods. For resumed sessions this 1984 field is the value from the resumed session state. 1986 extensions 1987 A list of extensions. Note that only extensions offered by the 1988 client can appear in the server's list. 1990 7.4.1.4 Hello Extensions 1992 The extension format is: 1994 struct { 1995 ExtensionType extension_type; 1996 opaque extension_data<0..2^16-1>; 1997 } Extension; 1999 enum { 2000 signature_algorithms(TBD-BY-IANA), (65535) 2001 } ExtensionType; 2003 Here: 2005 - "extension_type" identifies the particular extension type. 2007 - "extension_data" contains information specific to the particular 2008 extension type. 2010 The initial set of extensions is defined in a companion document 2011 [TLSEXT]. The list of extension types is maintained by IANA as 2012 described in Section 12. 2014 There are subtle (and not so subtle) interactions that may occur in 2015 this protocol between new features and existing features which may 2016 result in a significant reduction in overall security, The following 2017 considerations should be taken into account when designing new 2018 extensions: 2020 - Some cases where a server does not agree to an extension are error 2021 conditions, and some simply a refusal to support a particular 2022 feature. In general error alerts should be used for the former, 2023 and a field in the server extension response for the latter. 2025 - Extensions should as far as possible be designed to prevent any 2026 attack that forces use (or non-use) of a particular feature by 2027 manipulation of handshake messages. This principle should be 2028 followed regardless of whether the feature is believed to cause a 2029 security problem. 2031 Often the fact that the extension fields are included in the 2032 inputs to the Finished message hashes will be sufficient, but 2033 extreme care is needed when the extension changes the meaning of 2034 messages sent in the handshake phase. Designers and implementors 2035 should be aware of the fact that until the handshake has been 2036 authenticated, active attackers can modify messages and insert, 2037 remove, or replace extensions. 2039 - It would be technically possible to use extensions to change major 2040 aspects of the design of TLS; for example the design of cipher 2041 suite negotiation. This is not recommended; it would be more 2042 appropriate to define a new version of TLS - particularly since 2043 the TLS handshake algorithms have specific protection against 2044 version rollback attacks based on the version number, and the 2045 possibility of version rollback should be a significant 2046 consideration in any major design change. 2048 7.4.1.4.1 Signature Algorithms 2050 The client uses the "signature_algorithms" extension to indicate to 2051 the server which signature/hash algorithm pairs may be used in 2052 digital signatures. The "extension_data" field of this extension 2053 contains a "supported_signature_algorithms" value. 2055 enum { 2056 none(0), md5(1), sha1(2), sha256(3), sha384(4), 2057 sha512(5), (255) 2058 } HashAlgorithm; 2060 enum { anonymous(0), rsa(1), dsa(2), ecdsa(3), (255) } 2061 SignatureAlgorithm; 2063 struct { 2064 HashAlgorithm hash; 2065 SignatureAlgorithm signature; 2066 } SignatureAndHashAlgorithm; 2068 SignatureAndHashAlgorithm 2069 supported_signature_algorithms<2..2^16-2>; 2071 Each SignatureAndHashAlgorithm value lists a single hash/signature 2072 pair which the client is willing to verify. The values are indicated 2073 in descending order of preference. 2075 Note: Because not all signature algorithms and hash algorithms may be 2076 accepted by an implementation (e.g., DSA with SHA-1, but not 2077 SHA-256), algorithms here are listed in pairs. 2079 hash 2080 This field indicates the hash algorithm which may be used. The 2081 values indicate support for unhashed data, MD5 [MD5], SHA-1, 2082 SHA-256, SHA-384, and SHA-512 [SHA] respectively. The "none" value 2083 is provided for future extensibility, in case of a signature 2084 algorithm which does not require hashing before signing. 2086 signature 2087 This field indicates the signature algorithm which may be used. 2088 The values indicate anonymous signatures, RSASSA-PKCS1-v1_5 2089 [PKCS1] and DSA [DSS] respectively. The "anonymous" value is 2090 meaningless in this context but used in Section 7.4.3. It MUST NOT 2091 appear in this extension. 2093 The semantics of this extension are somewhat complicated because the 2094 cipher suite indicates permissible signature algorithms but not hash 2095 algorithm. Sections 7.4.2 and 7.4.3 describe the appropriate rules. 2097 If the client supports only the default hash and signature algorithms 2098 (listed in this section), it MAY omit the signature_algorithms 2099 extension. If the client does not support the default algorithms, or 2100 supports other hash and signature algorithms (and it is willing to 2101 use them for verifying messages sent by server; server certificates 2102 and server key exchange), it MUST send the signature_algorithms 2103 extension listing the algorithms it is willing to accept. 2105 If the client does not send the signature_algorithms extension, the 2106 server MUST assume the following: 2108 - If the negotiated key exchange algorithm is one of (RSA, DHE_RSA, 2109 DH_RSA, RSA_PSK, ECDH_RSA, ECDHE_RSA), behave as if client had sent 2110 the value (sha1,rsa). 2112 - If the negotiated key exchange algorithm is one of (DHE_DSS, 2113 DH_DSS), behave as if the client had sent the value (sha1,dsa). 2115 - If the negotiated key exchange algorithm is one of (ECDH_ECDSA, 2116 ECDHE_ECDSA), behave as if the client had sent value (sha1,ecdsa). 2118 Note: this is a change from TLS 1.1 where there are no explicit rules 2119 but as a practical matter one can assume that the peer supports MD5 2120 and SHA-1. 2122 Note: this extension is not meaningful for TLS versions prior to 1.2. 2123 Clients MUST NOT offer it if they are offering prior versions. 2124 However, even if clients do offer it, the rules specified in [TLSEXT] 2125 require servers to ignore extensions they do not understand. 2127 Servers MUST NOT send this extension. TLS servers MUST support 2128 receiving this extension. 2130 7.4.2. Server Certificate 2132 When this message will be sent: 2134 The server MUST send a certificate whenever the agreed-upon key 2135 exchange method uses certificates for authentication (this 2136 includes all key exchange methods defined in this document except 2137 DH_anon). This message will always immediately follow the server 2138 hello message. 2140 Meaning of this message: 2142 This message conveys the server's certificate chain to the client. 2143 The certificate MUST be appropriate for the negotiated cipher 2144 suite's key exchange algorithm, and any negotiated extensions. 2146 Structure of this message: 2148 opaque ASN.1Cert<1..2^24-1>; 2150 struct { 2151 ASN.1Cert certificate_list<0..2^24-1>; 2152 } Certificate; 2154 certificate_list 2155 This is a sequence (chain) of certificates. The sender's 2156 certificate MUST come first in the list. Each following 2157 certificate MUST directly certify the one preceding it. Because 2158 certificate validation requires that root keys be distributed 2159 independently, the self-signed certificate that specifies the root 2160 certificate authority MAY optionally be omitted from the chain, 2161 under the assumption that the remote end must already possess it 2162 in order to validate it in any case. 2164 The same message type and structure will be used for the client's 2165 response to a certificate request message. Note that a client MAY 2166 send no certificates if it does not have an appropriate certificate 2167 to send in response to the server's authentication request. 2169 Note: PKCS #7 [PKCS7] is not used as the format for the certificate 2170 vector because PKCS #6 [PKCS6] extended certificates are not used. 2171 Also, PKCS #7 defines a SET rather than a SEQUENCE, making the task 2172 of parsing the list more difficult. 2174 The following rules apply to the certificates sent by the server: 2176 - The certificate type MUST be X.509v3, unless explicitly negotiated 2177 otherwise (e.g., [TLSPGP]). 2179 - The end entity certificate's public key (and associated 2180 restrictions) MUST be compatible with the selected key exchange 2181 algorithm. 2183 Key Exchange Alg. Certificate Key Type 2185 RSA RSA public key; the certificate MUST 2186 RSA_PSK allow the key to be used for encryption 2187 (the keyEncipherment bit MUST be set 2188 if the key usage extension is present). 2189 Note: RSA_PSK is defined in [TLSPSK]. 2191 DHE_RSA RSA public key; the certificate MUST 2192 ECDHE_RSA allow the key to be used for signing 2193 (the digitalSignature bit MUST be set 2194 if the key usage extension is present) 2195 with the signature scheme and hash 2196 algorithm that will be employed in the 2197 server key exchange message. 2199 DHE_DSS DSA public key; the certificate MUST 2200 allow the key to be used for signing with 2201 the hash algorithm that will be employed 2202 in the server key exchange message. 2204 DH_DSS Diffie-Hellman public key; the 2205 DH_RSA keyAgreement bit MUST be set if the 2206 key usage extension is present. 2208 ECDH_ECDSA ECDH-capable public key; the public key 2209 ECDH_RSA MUST use a curve and point format supported 2210 by the client, as described in [TLSECC]. 2212 ECDHE_ECDSA ECDSA-capable public key; the certificate 2213 MUST allow the key to be used for signing 2214 with the hash algorithm that will be 2215 employed in the server key exchange 2216 message. The public key MUST use a curve 2217 and point format supported by the client, 2218 as described in [TLSECC]. 2220 - The "server_name" and "trusted_ca_keys" extensions [TLSEXT] are 2221 used to guide certificate selection. 2223 If the client provided a "signature_algorithms" extension, then all 2224 certificates provided by the server MUST be signed by a 2225 hash/signature algorithm pair that appears in that extension. Note 2226 that this implies that a certificate containing a key for one 2227 signature algorithm MAY be signed using a different signature 2228 algorithm (for instance, an RSA key signed with a DSA key.) This is a 2229 departure from TLS 1.1, which required that the algorithms be the 2230 same. Note that this also implies that the DH_DSS, DH_RSA, 2231 ECDH_ECDSA, and ECDH_RSA key exchange algorithms do not restrict the 2232 algorithm used to sign the certificate. Fixed DH certificates MAY be 2233 signed with any hash/signature algorithm pair appearing in the 2234 extension. The naming is historical. 2236 If the server has multiple certificates, it chooses one of them based 2237 on the above-mentioned criteria (in addition to other criteria, such 2238 as transport layer endpoint, local configuration and preferences, 2239 etc.). If the server has a single certificate it SHOULD attempt to 2240 validate that it meets these criteria. 2242 Note that there are certificates that use algorithms and/or algorithm 2243 combinations that cannot be currently used with TLS. For example, a 2244 certificate with RSASSA-PSS signature key (id-RSASSA-PSS OID in 2245 SubjectPublicKeyInfo) cannot be used because TLS defines no 2246 corresponding signature algorithm. 2248 As cipher suites that specify new key exchange methods are specified 2249 for the TLS Protocol, they will imply certificate format and the 2250 required encoded keying information. 2252 7.4.3. Server Key Exchange Message 2254 When this message will be sent: 2256 This message will be sent immediately after the server certificate 2257 message (or the server hello message, if this is an anonymous 2258 negotiation). 2260 The server key exchange message is sent by the server only when 2261 the server certificate message (if sent) does not contain enough 2262 data to allow the client to exchange a premaster secret. This is 2263 true for the following key exchange methods: 2265 DHE_DSS 2266 DHE_RSA 2267 DH_anon 2269 It is not legal to send the server key exchange message for the 2270 following key exchange methods: 2272 RSA 2273 DH_DSS 2274 DH_RSA 2276 Meaning of this message: 2278 This message conveys cryptographic information to allow the client 2279 to communicate the premaster secret: a Diffie-Hellman public key 2280 with which the client can complete a key exchange (with the result 2281 being the premaster secret) or a public key for some other 2282 algorithm. 2284 Structure of this message: 2286 enum { dhe_dss, dhe_rsa, dh_anon, rsa, dh_dss, dh_rsa } 2287 KeyExchangeAlgorithm; 2289 struct { 2290 opaque dh_p<1..2^16-1>; 2291 opaque dh_g<1..2^16-1>; 2292 opaque dh_Ys<1..2^16-1>; 2293 } ServerDHParams; /* Ephemeral DH parameters */ 2295 dh_p 2296 The prime modulus used for the Diffie-Hellman operation. 2298 dh_g 2299 The generator used for the Diffie-Hellman operation. 2301 dh_Ys 2302 The server's Diffie-Hellman public value (g^X mod p). 2304 struct { 2305 select (KeyExchangeAlgorithm) { 2306 case dh_anon: 2307 ServerDHParams params; 2308 case dhe_dss: 2309 case dhe_rsa: 2310 ServerDHParams params; 2311 digitally-signed struct { 2312 opaque client_random[32]; 2313 opaque server_random[32]; 2314 ServerDHParams params; 2315 } signed_params; 2316 case rsa: 2317 case dh_dss: 2318 case dh_rsa: 2319 struct {} ; 2320 /* message is omitted for rsa, dh_dss, and dh_rsa */ 2321 }; 2322 } ServerKeyExchange; 2324 params 2325 The server's key exchange parameters. 2327 signed_params 2328 For non-anonymous key exchanges, a signature over the 2329 server's key exchange parameters. 2331 If the client has offered the "signature_algorithms" extension, the 2332 signature algorithm and hash algorithm MUST be a pair listed in that 2333 extension. Note that there is a possibility for inconsistencies here. 2334 For instance, the client might offer DHE_DSS key exchange but omit 2335 any DSS pairs from its "signature_algorithms" extension. In order to 2336 negotiate correctly, the server MUST check any candidate cipher 2337 suites against the "signature_algorithms" extension before selecting 2338 them. This is somewhat inelegant but is a compromise designed to 2339 minimize changes to the original cipher suite design. 2341 In addition, the hash and signature algorithms MUST be compatible 2342 with the key in the server's end-entity certificate. RSA keys MAY be 2343 used with any permitted hash algorithm, subject to restrictions in 2344 the certificate, if any. 2346 Because DSA signatures do not contain any secure indication of hash 2347 algorithm, there is a risk of hash substitution if multiple hashes 2348 may be used with any key. Currently, DSS [DSS] may only be used with 2349 SHA-1. Future revisions of DSS [DSS-3] are expected to allow other 2350 digest algorithms, as well as guidance as to which digest algorithms 2351 should be used with each key size. In addition, future revisions of 2353 [PKIX] may specify mechanisms for certificates to indicate which 2354 digest algorithms are to be used with DSA. 2356 As additional cipher suites are defined for TLS that include new key 2357 exchange algorithms, the server key exchange message will be sent if 2358 and only if the certificate type associated with the key exchange 2359 algorithm does not provide enough information for the client to 2360 exchange a premaster secret. 2362 7.4.4. Certificate Request 2364 When this message will be sent: 2366 A non-anonymous server can optionally request a certificate from 2367 the client, if appropriate for the selected cipher suite. This 2368 message, if sent, will immediately follow the Server Key Exchange 2369 message (if it is sent; otherwise, the Server Certificate 2370 message). 2372 Structure of this message: 2374 enum { 2375 rsa_sign(1), dss_sign(2), rsa_fixed_dh(3), dss_fixed_dh(4), 2376 rsa_ephemeral_dh_RESERVED(5), dss_ephemeral_dh_RESERVED(6), 2377 fortezza_dms_RESERVED(20), (255) 2378 } ClientCertificateType; 2380 opaque DistinguishedName<1..2^16-1>; 2382 struct { 2383 ClientCertificateType certificate_types<1..2^8-1>; 2384 SignatureAndHashAlgorithm 2385 supported_signature_algorithms<2^16-1>; 2386 DistinguishedName certificate_authorities<0..2^16-1>; 2387 } CertificateRequest; 2389 certificate_types 2390 A list of the types of certificate types which the client may 2391 offer. 2393 rsa_sign a certificate containing an RSA key 2394 dss_sign a certificate containing a DSS key 2395 rsa_fixed_dh a certificate containing a static DH key. 2396 dss_fixed_dh a certificate containing a static DH key 2398 supported_signature_algorithms 2399 A list of the hash/signature algorithm pairs that the server is 2400 able to verify, listed in descending order of preference. 2402 certificate_authorities 2403 A list of the distinguished names [X501] of acceptable 2404 certificate_authorities, represented in DER-encoded format. These 2405 distinguished names may specify a desired distinguished name for a 2406 root CA or for a subordinate CA; thus, this message can be used 2407 both to describe known roots and a desired authorization space. If 2408 the certificate_authorities list is empty then the client MAY send 2409 any certificate of the appropriate ClientCertificateType, unless 2410 there is some external arrangement to the contrary. 2412 The interaction of the certificate_types and 2413 supported_signature_algorithms fields is somewhat complicated. 2414 certificate_types has been present in TLS since SSLv3, but was 2415 somewhat underspecified. Much of its functionality is superseded by 2416 supported_signature_algorithms. The following rules apply: 2418 - Any certificates provided by the client MUST be signed using a 2419 hash/signature algorithm pair found in 2420 supported_signature_algorithms. 2422 - The end-entity certificate provided by the client MUST contain a 2423 key which is compatible with certificate_types. If the key is a 2424 signature key, it MUST be usable with some hash/signature 2425 algorithm pair in supported_signature_algorithms. 2427 - For historical reasons, the names of some client certificate types 2428 include the algorithm used to sign the certificate. For example, 2429 in earlier versions of TLS, rsa_fixed_dh meant a certificate 2430 signed with RSA and containing a static DH key. In TLS 1.2, this 2431 functionality has been obsoleted by the 2432 supported_signature_algorithms, and the certificate type no longer 2433 restricts the algorithm used to sign the certificate. For 2434 example, if the server sends dss_fixed_dh certificate type and 2435 {{sha1, dsa}, {sha1, rsa}} signature types, the client MAY reply 2436 with a certificate containing a static DH key, signed with RSA- 2437 SHA1. 2439 New ClientCertificateType values are assigned by IANA as described in 2440 Section 12. 2442 Note: Values listed as RESERVED may not be used. They were used in 2443 SSLv3. 2445 Note: It is a fatal handshake_failure alert for an anonymous server 2446 to request client authentication. 2448 7.4.5 Server hello done 2449 When this message will be sent: 2451 The server hello done message is sent by the server to indicate 2452 the end of the server hello and associated messages. After sending 2453 this message, the server will wait for a client response. 2455 Meaning of this message: 2457 This message means that the server is done sending messages to 2458 support the key exchange, and the client can proceed with its 2459 phase of the key exchange. 2461 Upon receipt of the server hello done message, the client SHOULD 2462 verify that the server provided a valid certificate, if required 2463 and check that the server hello parameters are acceptable. 2465 Structure of this message: 2467 struct { } ServerHelloDone; 2469 7.4.6. Client Certificate 2471 When this message will be sent: 2473 This is the first message the client can send after receiving a 2474 server hello done message. This message is only sent if the server 2475 requests a certificate. If no suitable certificate is available, 2476 the client MUST send a certificate message containing no 2477 certificates. That is, the certificate_list structure has a length 2478 of zero. If the client does not send any certificates, the server 2479 MAY at its discretion either continue the handshake without client 2480 authentication, or respond with a fatal handshake_failure alert. 2481 Also, if some aspect of the certificate chain was unacceptable 2482 (e.g., it was not signed by a known, trusted CA), the server MAY 2483 at its discretion either continue the handshake (considering the 2484 client unauthenticated) or send a fatal alert. 2486 Client certificates are sent using the Certificate structure 2487 defined in Section 7.4.2. 2489 Meaning of this message: 2491 This message conveys the client's certificate chain to the server; 2492 the server will use it when verifying the certificate verify 2493 message (when the client authentication is based on signing), or 2494 calculate the premaster secret (for non-ephemeral Diffie-Hellman). 2495 The certificate MUST be appropriate for the negotiated cipher 2496 suite's key exchange algorithm, and any negotiated extensions. 2498 In particular: 2500 - The certificate type MUST be X.509v3, unless explicitly negotiated 2501 otherwise (e.g. [TLSPGP]). 2503 - The end-entity certificate's public key (and associated 2504 restrictions) has to be compatible with the certificate types 2505 listed in CertificateRequest: 2507 Client Cert. Type Certificate Key Type 2509 rsa_sign RSA public key; the certificate MUST allow 2510 the key to be used for signing with the 2511 signature scheme and hash algorithm that 2512 will be employed in the certificate verify 2513 message. 2515 dss_sign DSA public key; the certificate MUST allow 2516 the key to be used for signing with the 2517 hash algorithm that will be employed in 2518 the certificate verify message. 2520 ecdsa_sign ECDSA-capable public key; the certificate 2521 MUST allow the key to be used for signing 2522 with the hash algorithm that will be 2523 employed in the certificate verify 2524 message; the public key MUST use a 2525 curve and point format supported by the 2526 server. 2528 rsa_fixed_dh Diffie-Hellman public key; MUST use 2529 dss_fixed_dh the same parameters as server's key. 2531 rsa_fixed_ecdh ECDH-capable public key; MUST use 2532 ecdsa_fixed_ecdh the same curve as server's key, and 2533 MUST use a point format supported by 2534 the server. 2536 - If the certificate_authorities list in the certificate request 2537 message was non-empty, one of the certificates in the certificate 2538 chain SHOULD be issued by one of the listed CAs. 2540 - The certificates MUST be signed using an acceptable hash/ 2541 signature algorithm pair, as described in Section 7.4.4. Note that 2542 this relaxes the constraints on certificate signing algorithms 2543 found in prior versions of TLS. 2545 Note that as with the server certificate, there are certificates that 2546 use algorithms/algorithm combinations that cannot be currently used 2547 with TLS. 2549 7.4.7. Client Key Exchange Message 2551 When this message will be sent: 2553 This message is always sent by the client. It MUST immediately 2554 follow the client certificate message, if it is sent. Otherwise it 2555 MUST be the first message sent by the client after it receives the 2556 server hello done message. 2558 Meaning of this message: 2560 With this message, the premaster secret is set, either though 2561 direct transmission of the RSA-encrypted secret, or by the 2562 transmission of Diffie-Hellman parameters that will allow each 2563 side to agree upon the same premaster secret. 2565 When the client is using an ephemeral Diffie-Hellman exponent, 2566 then this message contains the client's Diffie-Hellman public 2567 value. If the client is sending a certificate containing a static 2568 DH exponent (i.e., it is doing fixed_dh client authentication) 2569 then this message MUST be sent but MUST be empty. 2571 Structure of this message: 2573 The choice of messages depends on which key exchange method has 2574 been selected. See Section 7.4.3 for the KeyExchangeAlgorithm 2575 definition. 2577 struct { 2578 select (KeyExchangeAlgorithm) { 2579 case rsa: 2580 EncryptedPreMasterSecret; 2581 case dhe_dss: 2582 case dhe_rsa: 2583 case dh_dss: 2584 case dh_rsa: 2585 case dh_anon: 2586 ClientDiffieHellmanPublic; 2587 } exchange_keys; 2588 } ClientKeyExchange; 2590 7.4.7.1. RSA Encrypted Premaster Secret Message 2592 Meaning of this message: 2594 If RSA is being used for key agreement and authentication, the 2595 client generates a 48-byte premaster secret, encrypts it using the 2596 public key from the server's certificate and sends the result in 2597 an encrypted premaster secret message. This structure is a variant 2598 of the client key exchange message and is not a message in itself. 2600 Structure of this message: 2602 struct { 2603 ProtocolVersion client_version; 2604 opaque random[46]; 2605 } PreMasterSecret; 2607 client_version 2608 The latest (newest) version supported by the client. This is 2609 used to detect version roll-back attacks. 2611 random 2612 46 securely-generated random bytes. 2614 struct { 2615 public-key-encrypted PreMasterSecret pre_master_secret; 2616 } EncryptedPreMasterSecret; 2618 pre_master_secret 2619 This random value is generated by the client and is used to 2620 generate the master secret, as specified in Section 8.1. 2622 Note: The version number in the PreMasterSecret is the version 2623 offered by the client in the ClientHello.client_version, not the 2624 version negotiated for the connection. This feature is designed to 2625 prevent rollback attacks. Unfortunately, some old implementations 2626 use the negotiated version instead and therefore checking the version 2627 number may lead to failure to interoperate with such incorrect client 2628 implementations. 2630 Client implementations MUST always send the correct version number in 2631 PreMasterSecret. If ClientHello.client_version is TLS 1.1 or higher, 2632 server implementations MUST check the version number as described in 2633 the note below. If the version number is 1.0 or earlier, server 2634 implementations SHOULD check the version number, but MAY have a 2635 configuration option to disable the check. Note that if the check 2636 fails, the PreMasterSecret SHOULD be randomized as described below. 2638 Note: Attacks discovered by Bleichenbacher [BLEI] and Klima et al. 2639 [KPR03] can be used to attack a TLS server that reveals whether a 2640 particular message, when decrypted, is properly PKCS#1 formatted, 2641 contains a valid PreMasterSecret structure, or has the correct 2642 version number. 2644 The best way to avoid these vulnerabilities is to treat incorrectly 2645 formatted messages in a manner indistinguishable from correctly 2646 formatted RSA blocks. In other words: 2648 1. Generate a string R of 46 random bytes 2650 2. Decrypt the message M 2652 3. If the PKCS#1 padding is not correct, or the length of 2653 message M is not exactly 48 bytes: 2654 premaster secret = ClientHello.client_version || R 2655 else If ClientHello.client_version <= TLS 1.0, and 2656 version number check is explicitly disabled: 2657 premaster secret = M 2658 else: 2659 premaster secret = ClientHello.client_version || M[2..47] 2661 Note that explicitly constructing the premaster_secret with the 2662 ClientHello.client_version produces an invalid master_secret if the 2663 client has sent the wrong version in the original premaster_secret. 2665 In any case, a TLS server MUST NOT generate an alert if processing an 2666 RSA-encrypted premaster secret message fails, or the version number 2667 is not as expected. Instead, it MUST continue the handshake with a 2668 randomly generated premaster secret. It may be useful to log the 2669 real cause of failure for troubleshooting purposes; however, care 2670 must be taken to avoid leaking the information to an attacker 2671 (through, e.g., timing, log files, or other channels.) 2673 The RSAES-OAEP encryption scheme defined in [PKCS1] is more secure 2674 against the Bleichenbacher attack. However, for maximal compatibility 2675 with earlier versions of TLS, this specification uses the RSAES- 2676 PKCS1-v1_5 scheme. No variants of the Bleichenbacher attack are known 2677 to exist provided that the above recommendations are followed. 2679 Implementation Note: Public-key-encrypted data is represented as an 2680 opaque vector <0..2^16-1> (see Section 4.7). Thus, the RSA-encrypted 2681 PreMasterSecret in a ClientKeyExchange is preceded by two length 2682 bytes. These bytes are redundant in the case of RSA because the 2683 EncryptedPreMasterSecret is the only data in the ClientKeyExchange 2684 and its length can therefore be unambiguously determined. The SSLv3 2685 specification was not clear about the encoding of public-key- 2686 encrypted data, and therefore many SSLv3 implementations do not 2687 include the the length bytes, encoding the RSA encrypted data 2688 directly in the ClientKeyExchange message. 2690 This specification requires correct encoding of the 2691 EncryptedPreMasterSecret complete with length bytes. The resulting 2692 PDU is incompatible with many SSLv3 implementations. Implementors 2693 upgrading from SSLv3 MUST modify their implementations to generate 2694 and accept the correct encoding. Implementors who wish to be 2695 compatible with both SSLv3 and TLS should make their implementation's 2696 behavior dependent on the protocol version. 2698 Implementation Note: It is now known that remote timing-based attacks 2699 on TLS are possible, at least when the client and server are on the 2700 same LAN. Accordingly, implementations that use static RSA keys MUST 2701 use RSA blinding or some other anti-timing technique, as described in 2702 [TIMING]. 2704 7.4.7.2. Client Diffie-Hellman Public Value 2706 Meaning of this message: 2708 This structure conveys the client's Diffie-Hellman public value 2709 (Yc) if it was not already included in the client's certificate. 2710 The encoding used for Yc is determined by the enumerated 2711 PublicValueEncoding. This structure is a variant of the client key 2712 exchange message, and not a message in itself. 2714 Structure of this message: 2716 enum { implicit, explicit } PublicValueEncoding; 2718 implicit 2719 If the client has sent a certificate which contains a suitable 2720 Diffie-Hellman key (for fixed_dh client authentication) then Yc 2721 is implicit and does not need to be sent again. In this case, 2722 the client key exchange message will be sent, but it MUST be 2723 empty. 2725 explicit 2726 Yc needs to be sent. 2728 struct { 2729 select (PublicValueEncoding) { 2730 case implicit: struct { }; 2731 case explicit: opaque dh_Yc<1..2^16-1>; 2732 } dh_public; 2733 } ClientDiffieHellmanPublic; 2735 dh_Yc 2736 The client's Diffie-Hellman public value (Yc). 2738 7.4.8. Certificate verify 2740 When this message will be sent: 2742 This message is used to provide explicit verification of a client 2743 certificate. This message is only sent following a client 2744 certificate that has signing capability (i.e. all certificates 2745 except those containing fixed Diffie-Hellman parameters). When 2746 sent, it MUST immediately follow the client key exchange message. 2748 Structure of this message: 2750 struct { 2751 digitally-signed struct { 2752 opaque handshake_messages[handshake_messages_length]; 2753 } 2754 } CertificateVerify; 2756 Here handshake_messages refers to all handshake messages sent or 2757 received starting at client hello up to but not including this 2758 message, including the type and length fields of the handshake 2759 messages. This is the concatenation of all the Handshake 2760 structures as defined in 7.4 exchanged thus far. Note that this 2761 requires both sides to either buffer the messages or compute 2762 running hashes for all potential hash algorithms up to the time of 2763 the CertificateVerify computation. Servers can minimize this 2764 computation cost by offering a restricted set of digest algorithms 2765 in the CertificateRequest message. 2767 The hash and signature algorithms used in the signature MUST be 2768 one of those present in the supported_signature_algorithms field 2769 of the CertificateRequest message. In addition, the hash and 2770 signature algorithms MUST be compatible with the key in the 2771 client's end-entity certificate. RSA keys MAY be used with any 2772 permitted hash algorith, subject to restrictions in the 2773 certificate, if any. 2775 Because DSA signatures do not contain any secure indication of 2776 hash algorithm, there is a risk of hash substitution if multiple 2777 hashes may be used with any key. Currently, DSS [DSS] may only be 2778 used with SHA-1. Future revisions of DSS [DSS-3] are expected to 2779 allow other digest algorithms, as well as guidance as to which 2780 digest algorithms should be used with each key size. In addition, 2781 future revisions of [PKIX] may specify mechanisms for certificates 2782 to indicate which digest algorithms are to be used with DSA. 2784 7.4.9. Finished 2785 When this message will be sent: 2787 A finished message is always sent immediately after a change 2788 cipher spec message to verify that the key exchange and 2789 authentication processes were successful. It is essential that a 2790 change cipher spec message be received between the other handshake 2791 messages and the Finished message. 2793 Meaning of this message: 2795 The finished message is the first protected with the just- 2796 negotiated algorithms, keys, and secrets. Recipients of finished 2797 messages MUST verify that the contents are correct. Once a side 2798 has sent its Finished message and received and validated the 2799 Finished message from its peer, it may begin to send and receive 2800 application data over the connection. 2802 Structure of this message: 2804 struct { 2805 opaque verify_data[verify_data_length]; 2806 } Finished; 2808 verify_data 2809 PRF(master_secret, finished_label, Hash(handshake_messages)) 2810 [0..verify_data_length-1]; 2812 finished_label 2813 For Finished messages sent by the client, the string "client 2814 finished". For Finished messages sent by the server, the string 2815 "server finished". 2817 Hash denotes a Hash of the handshake messages. For the PRF defined 2818 in Section 5, the Hash MUST be the Hash used as the basis for the 2819 PRF. Any cipher suite which defines a different PRF MUST also 2820 define the Hash to use in the Finished computation. 2822 In previous versions of TLS, the verify_data was always 12 octets 2823 long. In the current version of TLS, it depends on the cipher 2824 suite. Any cipher suite which does not explicitly specify 2825 verify_data_length has a verify_data_length equal to 12. This 2826 includes all existing cipher suites. Note that this 2827 representation has the same encoding as with previous versions. 2828 Future cipher suites MAY specify other lengths but such length 2829 MUST be at least 12 bytes. 2831 handshake_messages 2832 All of the data from all messages in this handshake (not 2833 including any HelloRequest messages) up to but not including 2834 this message. This is only data visible at the handshake layer 2835 and does not include record layer headers. This is the 2836 concatenation of all the Handshake structures as defined in 2837 7.4, exchanged thus far. 2839 It is a fatal error if a finished message is not preceded by a change 2840 cipher spec message at the appropriate point in the handshake. 2842 The value handshake_messages includes all handshake messages starting 2843 at client hello up to, but not including, this finished message. This 2844 may be different from handshake_messages in Section 7.4.8 because it 2845 would include the certificate verify message (if sent). Also, the 2846 handshake_messages for the finished message sent by the client will 2847 be different from that for the finished message sent by the server, 2848 because the one that is sent second will include the prior one. 2850 Note: Change cipher spec messages, alerts, and any other record types 2851 are not handshake messages and are not included in the hash 2852 computations. Also, Hello Request messages are omitted from handshake 2853 hashes. 2855 8. Cryptographic Computations 2857 In order to begin connection protection, the TLS Record Protocol 2858 requires specification of a suite of algorithms, a master secret, and 2859 the client and server random values. The authentication, encryption, 2860 and MAC algorithms are determined by the cipher_suite selected by the 2861 server and revealed in the server hello message. The compression 2862 algorithm is negotiated in the hello messages, and the random values 2863 are exchanged in the hello messages. All that remains is to calculate 2864 the master secret. 2866 8.1. Computing the Master Secret 2868 For all key exchange methods, the same algorithm is used to convert 2869 the pre_master_secret into the master_secret. The pre_master_secret 2870 should be deleted from memory once the master_secret has been 2871 computed. 2873 master_secret = PRF(pre_master_secret, "master secret", 2874 ClientHello.random + ServerHello.random) 2875 [0..47]; 2877 The master secret is always exactly 48 bytes in length. The length of 2878 the premaster secret will vary depending on key exchange method. 2880 8.1.1. RSA 2882 When RSA is used for server authentication and key exchange, a 2883 48-byte pre_master_secret is generated by the client, encrypted under 2884 the server's public key, and sent to the server. The server uses its 2885 private key to decrypt the pre_master_secret. Both parties then 2886 convert the pre_master_secret into the master_secret, as specified 2887 above. 2889 8.1.2. Diffie-Hellman 2891 A conventional Diffie-Hellman computation is performed. The 2892 negotiated key (Z) is used as the pre_master_secret, and is converted 2893 into the master_secret, as specified above. Leading bytes of Z that 2894 contain all zero bits are stripped before it is used as the 2895 pre_master_secret. 2897 Note: Diffie-Hellman parameters are specified by the server and may 2898 be either ephemeral or contained within the server's certificate. 2900 9. Mandatory Cipher Suites 2902 In the absence of an application profile standard specifying 2903 otherwise, a TLS compliant application MUST implement the cipher 2904 suite TLS_RSA_WITH_AES_128_CBC_SHA. 2906 10. Application Data Protocol 2908 Application data messages are carried by the Record Layer and are 2909 fragmented, compressed, and encrypted based on the current connection 2910 state. The messages are treated as transparent data to the record 2911 layer. 2913 11. Security Considerations 2915 Security issues are discussed throughout this memo, especially in 2916 Appendices D, E, and F. 2918 12. IANA Considerations 2920 This document uses several registries that were originally created in 2921 [TLS1.1]. IANA is requested to update (has updated) these to 2922 reference this document. The registries and their allocation policies 2923 (unchanged from [TLS1.1]) are listed below. 2925 - TLS ClientCertificateType Identifiers Registry: Future values in 2926 the range 0-63 (decimal) inclusive are assigned via Standards 2927 Action [RFC2434]. Values in the range 64-223 (decimal) inclusive 2928 are assigned Specification Required [RFC2434]. Values from 224-255 2929 (decimal) inclusive are reserved for Private Use [RFC2434]. 2931 - TLS Cipher Suite Registry: Future values with the first byte in 2932 the range 0-191 (decimal) inclusive are assigned via Standards 2933 Action [RFC2434]. Values with the first byte in the range 192-254 2934 (decimal) are assigned via Specification Required [RFC2434]. 2935 Values with the first byte 255 (decimal) are reserved for Private 2936 Use [RFC2434]. 2938 - This document defines several new HMAC-SHA256 based cipher suites, 2939 whose values (in Appendix A.5) are to be (have been) allocated 2940 from the TLS Cipher Suite registry. 2942 - TLS ContentType Registry: Future values are allocated via 2943 Standards Action [RFC2434]. 2945 - TLS Alert Registry: Future values are allocated via Standards 2946 Action [RFC2434]. 2948 - TLS HandshakeType Registry: Future values are allocated via 2949 Standards Action [RFC2434]. 2951 This document also uses a registry originally created in [RFC4366]. 2952 IANA is requested to update (has updated) it to reference this 2953 document. The registry and its allocation policy (unchanged from 2954 [RFC4366]) is listed below: 2956 - TLS ExtensionType Registry: Future values are allocated via IETF 2957 Consensus [RFC2434] 2959 In addition, this document defines two new registries to be 2960 maintained by IANA: 2962 - TLS SignatureAlgorithm Registry: The registry will be initially 2963 populated with the values described in Section 7.4.1.4.1. Future 2964 values in the range 0-63 (decimal) inclusive are assigned via 2965 Standards Action [RFC2434]. Values in the range 64-223 (decimal) 2966 inclusive are assigned via Specification Required [RFC2434]. 2967 Values from 224-255 (decimal) inclusive are reserved for Private 2968 Use [RFC2434]. 2970 - TLS HashAlgorithm Registry: The registry will be initially 2971 populated with the values described in Section 7.4.1.4.1. Future 2972 values in the range 0-63 (decimal) inclusive are assigned via 2973 Standards Action [RFC2434]. Values in the range 64-223 (decimal) 2974 inclusive are assigned via Specification Required [RFC2434]. 2975 Values from 224-255 (decimal) inclusive are reserved for Private 2976 Use [RFC2434]. 2978 This document defines one new TLS extension, signature_algorithms, 2979 which is to be (has been) allocated value TBD-BY-IANA in the TLS 2980 ExtensionType registry. 2982 This document also uses the TLS Compression Method Identifiers 2983 Registry, defined in [RFC3749]. IANA is requested to allocate value 2984 0 for the "null" compression method. 2986 Appendix A. Protocol Constant Values 2988 This section describes protocol types and constants. 2990 A.1. Record Layer 2992 struct { 2993 uint8 major; 2994 uint8 minor; 2995 } ProtocolVersion; 2997 ProtocolVersion version = { 3, 3 }; /* TLS v1.2*/ 2999 enum { 3000 change_cipher_spec(20), alert(21), handshake(22), 3001 application_data(23), (255) 3002 } ContentType; 3004 struct { 3005 ContentType type; 3006 ProtocolVersion version; 3007 uint16 length; 3008 opaque fragment[TLSPlaintext.length]; 3009 } TLSPlaintext; 3011 struct { 3012 ContentType type; 3013 ProtocolVersion version; 3014 uint16 length; 3015 opaque fragment[TLSCompressed.length]; 3016 } TLSCompressed; 3018 struct { 3019 ContentType type; 3020 ProtocolVersion version; 3021 uint16 length; 3022 select (SecurityParameters.cipher_type) { 3023 case stream: GenericStreamCipher; 3024 case block: GenericBlockCipher; 3025 case aead: GenericAEADCipher; 3026 } fragment; 3027 } TLSCiphertext; 3029 stream-ciphered struct { 3030 opaque content[TLSCompressed.length]; 3031 opaque MAC[SecurityParameters.mac_length]; 3032 } GenericStreamCipher; 3033 struct { 3034 opaque IV[SecurityParameters.record_iv_length]; 3035 block-ciphered struct { 3036 opaque content[TLSCompressed.length]; 3037 opaque MAC[SecurityParameters.mac_length]; 3038 uint8 padding[GenericBlockCipher.padding_length]; 3039 uint8 padding_length; 3040 }; 3041 } GenericBlockCipher; 3043 aead-ciphered struct { 3044 opaque IV[SecurityParameters.record_iv_length]; 3045 opaque aead_output[AEADEncrypted.length]; 3046 } GenericAEADCipher; 3048 A.2. Change Cipher Specs Message 3050 struct { 3051 enum { change_cipher_spec(1), (255) } type; 3052 } ChangeCipherSpec; 3054 A.3. Alert Messages 3056 enum { warning(1), fatal(2), (255) } AlertLevel; 3058 enum { 3059 close_notify(0), 3060 unexpected_message(10), 3061 bad_record_mac(20), 3062 decryption_failed_RESERVED(21), 3063 record_overflow(22), 3064 decompression_failure(30), 3065 handshake_failure(40), 3066 no_certificate_RESERVED(41), 3067 bad_certificate(42), 3068 unsupported_certificate(43), 3069 certificate_revoked(44), 3070 certificate_expired(45), 3071 certificate_unknown(46), 3072 illegal_parameter(47), 3073 unknown_ca(48), 3074 access_denied(49), 3075 decode_error(50), 3076 decrypt_error(51), 3077 export_restriction_RESERVED(60), 3078 protocol_version(70), 3079 insufficient_security(71), 3080 internal_error(80), 3081 user_canceled(90), 3082 no_renegotiation(100), 3083 unsupported_extension(110), /* new */ 3084 (255) 3085 } AlertDescription; 3087 struct { 3088 AlertLevel level; 3089 AlertDescription description; 3090 } Alert; 3092 A.4. Handshake Protocol 3094 enum { 3095 hello_request(0), client_hello(1), server_hello(2), 3096 certificate(11), server_key_exchange (12), 3097 certificate_request(13), server_hello_done(14), 3098 certificate_verify(15), client_key_exchange(16), 3099 finished(20) 3100 (255) 3101 } HandshakeType; 3103 struct { 3104 HandshakeType msg_type; 3105 uint24 length; 3106 select (HandshakeType) { 3107 case hello_request: HelloRequest; 3108 case client_hello: ClientHello; 3109 case server_hello: ServerHello; 3110 case certificate: Certificate; 3111 case server_key_exchange: ServerKeyExchange; 3112 case certificate_request: CertificateRequest; 3113 case server_hello_done: ServerHelloDone; 3114 case certificate_verify: CertificateVerify; 3115 case client_key_exchange: ClientKeyExchange; 3116 case finished: Finished; 3117 } body; 3118 } Handshake; 3120 A.4.1. Hello Messages 3122 struct { } HelloRequest; 3124 struct { 3125 uint32 gmt_unix_time; 3126 opaque random_bytes[28]; 3127 } Random; 3128 opaque SessionID<0..32>; 3130 uint8 CipherSuite[2]; 3132 enum { null(0), (255) } CompressionMethod; 3134 struct { 3135 ProtocolVersion client_version; 3136 Random random; 3137 SessionID session_id; 3138 CipherSuite cipher_suites<2..2^16-2>; 3139 CompressionMethod compression_methods<1..2^8-1>; 3140 select (extensions_present) { 3141 case false: 3142 struct {}; 3143 case true: 3144 Extension extensions<0..2^16-1>; 3145 }; 3146 } ClientHello; 3148 struct { 3149 ProtocolVersion server_version; 3150 Random random; 3151 SessionID session_id; 3152 CipherSuite cipher_suite; 3153 CompressionMethod compression_method; 3154 select (extensions_present) { 3155 case false: 3156 struct {}; 3157 case true: 3158 Extension extensions<0..2^16-1>; 3159 }; 3160 } ServerHello; 3162 struct { 3163 ExtensionType extension_type; 3164 opaque extension_data<0..2^16-1>; 3165 } Extension; 3167 enum { 3168 signature_algorithms(TBD-BY-IANA), (65535) 3169 } ExtensionType; 3171 enum{ 3172 none(0), md5(1), sha1(2), sha256(3), sha384(4), 3173 sha512(5), (255) 3174 } HashAlgorithm; 3175 enum { anonymous(0), rsa(1), dsa(2), (255) } SignatureAlgorithm; 3177 struct { 3178 HashAlgorithm hash; 3179 SignatureAlgorithm signature; 3180 } SignatureAndHashAlgorithm; 3182 SignatureAndHashAlgorithm 3183 supported_signature_algorithms<2..2^16-1>; 3185 A.4.2. Server Authentication and Key Exchange Messages 3187 opaque ASN.1Cert<2^24-1>; 3189 struct { 3190 ASN.1Cert certificate_list<0..2^24-1>; 3191 } Certificate; 3193 enum { dhe_dss, dhe_rsa, dh_anon, rsa,dh_dss, dh_rsa} 3194 KeyExchangeAlgorithm; 3196 struct { 3197 opaque dh_p<1..2^16-1>; 3198 opaque dh_g<1..2^16-1>; 3199 opaque dh_Ys<1..2^16-1>; 3200 } ServerDHParams; /* Ephemeral DH parameters */ 3202 struct { 3203 select (KeyExchangeAlgorithm) { 3204 case dh_anon: 3205 ServerDHParams params; 3206 case dhe_dss: 3207 case dhe_rsa: 3208 ServerDHParams params; 3209 digitally-signed struct { 3210 opaque client_random[32]; 3211 opaque server_random[32]; 3212 ServerDHParams params; 3213 } signed_params; 3214 case rsa: 3215 case dh_dss: 3216 case dh_rsa: 3217 struct {} ; 3218 /* message is omitted for rsa, dh_dss, and dh_rsa */ 3219 }; 3220 } ServerKeyExchange; 3221 enum { 3222 rsa_sign(1), dss_sign(2), rsa_fixed_dh(3), dss_fixed_dh(4), 3223 rsa_ephemeral_dh_RESERVED(5), dss_ephemeral_dh_RESERVED(6), 3224 fortezza_dms_RESERVED(20), 3225 (255) 3226 } ClientCertificateType; 3228 opaque DistinguishedName<1..2^16-1>; 3230 struct { 3231 ClientCertificateType certificate_types<1..2^8-1>; 3232 DistinguishedName certificate_authorities<0..2^16-1>; 3233 } CertificateRequest; 3235 struct { } ServerHelloDone; 3237 A.4.3. Client Authentication and Key Exchange Messages 3239 struct { 3240 select (KeyExchangeAlgorithm) { 3241 case rsa: 3242 EncryptedPreMasterSecret; 3243 case dhe_dss: 3244 case dhe_rsa: 3245 case dh_dss: 3246 case dh_rsa: 3247 case dh_anon: 3248 ClientDiffieHellmanPublic; 3249 } exchange_keys; 3250 } ClientKeyExchange; 3252 struct { 3253 ProtocolVersion client_version; 3254 opaque random[46]; 3255 } PreMasterSecret; 3257 struct { 3258 public-key-encrypted PreMasterSecret pre_master_secret; 3259 } EncryptedPreMasterSecret; 3261 enum { implicit, explicit } PublicValueEncoding; 3263 struct { 3264 select (PublicValueEncoding) { 3265 case implicit: struct {}; 3266 case explicit: opaque DH_Yc<1..2^16-1>; 3267 } dh_public; 3268 } ClientDiffieHellmanPublic; 3269 struct { 3270 digitally-signed struct { 3271 opaque handshake_messages[handshake_messages_length]; 3272 } 3273 } CertificateVerify; 3275 A.4.4. Handshake Finalization Message 3277 struct { 3278 opaque verify_data[verify_data_length]; 3279 } Finished; 3281 A.5. The Cipher Suite 3283 The following values define the cipher suite codes used in the client 3284 hello and server hello messages. 3286 A cipher suite defines a cipher specification supported in TLS 3287 Version 1.2. 3289 TLS_NULL_WITH_NULL_NULL is specified and is the initial state of a 3290 TLS connection during the first handshake on that channel, but MUST 3291 NOT be negotiated, as it provides no more protection than an 3292 unsecured connection. 3294 CipherSuite TLS_NULL_WITH_NULL_NULL = { 0x00,0x00 }; 3296 The following CipherSuite definitions require that the server provide 3297 an RSA certificate that can be used for key exchange. The server may 3298 request any signature-capable certificate in the certificate request 3299 message. 3301 CipherSuite TLS_RSA_WITH_NULL_MD5 = { 0x00,0x01 }; 3302 CipherSuite TLS_RSA_WITH_NULL_SHA = { 0x00,0x02 }; 3303 CipherSuite TLS_RSA_WITH_NULL_SHA256 = { 0x00,TBD1 }; 3304 CipherSuite TLS_RSA_WITH_RC4_128_MD5 = { 0x00,0x04 }; 3305 CipherSuite TLS_RSA_WITH_RC4_128_SHA = { 0x00,0x05 }; 3306 CipherSuite TLS_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x0A }; 3307 CipherSuite TLS_RSA_WITH_AES_128_CBC_SHA = { 0x00,0x2F }; 3308 CipherSuite TLS_RSA_WITH_AES_256_CBC_SHA = { 0x00,0x35 }; 3309 CipherSuite TLS_RSA_WITH_AES_128_CBC_SHA256 = { 0x00,TBD2 }; 3310 CipherSuite TLS_RSA_WITH_AES_256_CBC_SHA256 = { 0x00,TBD3 }; 3312 The following cipher suite definitions are used for server- 3313 authenticated (and optionally client-authenticated) Diffie-Hellman. 3314 DH denotes cipher suites in which the server's certificate contains 3315 the Diffie-Hellman parameters signed by the certificate authority 3316 (CA). DHE denotes ephemeral Diffie-Hellman, where the Diffie-Hellman 3317 parameters are signed by a a signature-capable certificate, which has 3318 been signed by the CA. The signing algorithm used by the server is 3319 specified after the DHE parameter. The server can request any 3320 signature-capable certificate from the client for client 3321 authentication or it may request a Diffie-Hellman certificate. Any 3322 Diffie-Hellman certificate provided by the client must use the 3323 parameters (group and generator) described by the server. 3325 CipherSuite TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA = { 0x00,0x0D }; 3326 CipherSuite TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x10 }; 3327 CipherSuite TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA = { 0x00,0x13 }; 3328 CipherSuite TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x16 }; 3329 CipherSuite TLS_DH_DSS_WITH_AES_128_CBC_SHA = { 0x00,0x30 }; 3330 CipherSuite TLS_DH_RSA_WITH_AES_128_CBC_SHA = { 0x00,0x31 }; 3331 CipherSuite TLS_DHE_DSS_WITH_AES_128_CBC_SHA = { 0x00,0x32 }; 3332 CipherSuite TLS_DHE_RSA_WITH_AES_128_CBC_SHA = { 0x00,0x33 }; 3333 CipherSuite TLS_DH_DSS_WITH_AES_256_CBC_SHA = { 0x00,0x36 }; 3334 CipherSuite TLS_DH_RSA_WITH_AES_256_CBC_SHA = { 0x00,0x37 }; 3335 CipherSuite TLS_DHE_DSS_WITH_AES_256_CBC_SHA = { 0x00,0x38 }; 3336 CipherSuite TLS_DHE_RSA_WITH_AES_256_CBC_SHA = { 0x00,0x39 }; 3337 CipherSuite TLS_DH_DSS_WITH_AES_128_CBC_SHA256 = { 0x00, TBD4}; 3338 CipherSuite TLS_DH_RSA_WITH_AES_128_CBC_SHA256 = { 0x00, TBD5}; 3339 CipherSuite TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 = { 0x00, TBD6}; 3340 CipherSuite TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 = { 0x00, TBD7}; 3341 CipherSuite TLS_DH_DSS_WITH_AES_256_CBC_SHA256 = { 0x00, TBD8}; 3342 CipherSuite TLS_DH_RSA_WITH_AES_256_CBC_SHA256 = { 0x00, TBD9}; 3343 CipherSuite TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 = { 0x00, TBDA}; 3344 CipherSuite TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 = { 0x00, TBDB}; 3346 The following cipher suites are used for completely anonymous Diffie- 3347 Hellman communications in which neither party is authenticated. Note 3348 that this mode is vulnerable to man-in-the-middle attacks. Using 3349 this mode therefore is of limited use: These cipher suites MUST NOT 3350 be used by TLS 1.2 implementations unless the application layer has 3351 specifically requested to allow anonymous key exchange. (Anonymous 3352 key exchange may sometimes be acceptable, for example, to support 3353 opportunistic encryption when no set-up for authentication is in 3354 place, or when TLS is used as part of more complex security protocols 3355 that have other means to ensure authentication.) 3357 CipherSuite TLS_DH_anon_WITH_RC4_128_MD5 = { 0x00,0x18 }; 3358 CipherSuite TLS_DH_anon_WITH_3DES_EDE_CBC_SHA = { 0x00,0x1B }; 3359 CipherSuite TLS_DH_anon_WITH_AES_128_CBC_SHA = { 0x00,0x34 }; 3360 CipherSuite TLS_DH_anon_WITH_AES_256_CBC_SHA = { 0x00,0x3A }; 3361 CipherSuite TLS_DH_anon_WITH_AES_128_CBC_SHA256 = { 0x00, TBDC}; 3362 CipherSuite TLS_DH_anon_WITH_AES_256_CBC_SHA256 = { 0x00, TBDD}; 3364 Note that using non-anonymous key exchange without actually verifying 3365 the key exchange is essentially equivalent to anonymous key exchange, 3366 and the same precautions apply. While non-anonymous key exchange 3367 will generally involve a higher computational and communicational 3368 cost than anonymous key exchange, it may be in the interest of 3369 interoperability not to disable non-anonymous key exchange when the 3370 application layer is allowing anonymous key exchange. 3372 New cipher suite values are assigned by IANA as described in Section 3373 12. 3375 Note: The cipher suite values { 0x00, 0x1C } and { 0x00, 0x1D } are 3376 reserved to avoid collision with Fortezza-based cipher suites in SSL 3377 3. 3379 A.6. The Security Parameters 3381 These security parameters are determined by the TLS Handshake 3382 Protocol and provided as parameters to the TLS Record Layer in order 3383 to initialize a connection state. SecurityParameters includes: 3385 enum { null(0), (255) } CompressionMethod; 3387 enum { server, client } ConnectionEnd; 3389 enum { tls_prf_sha256 } PRFAlgorithm; 3391 enum { null, rc4, 3des, aes } 3392 BulkCipherAlgorithm; 3394 enum { stream, block, aead } CipherType; 3396 enum { null, hmac_md5, hmac_sha, hmac_sha256, hmac_sha384, 3397 hmac_sha512} MACAlgorithm; 3399 /* The algorithms specified in CompressionMethod, 3400 BulkCipherAlgorithm, and MACAlgorithm may be added to. */ 3402 struct { 3403 ConnectionEnd entity; 3404 PRFAlgorithm prf_algorithm; 3405 BulkCipherAlgorithm bulk_cipher_algorithm; 3406 CipherType cipher_type; 3407 uint8 enc_key_length; 3408 uint8 block_length; 3409 uint8 fixed_iv_length; 3410 uint8 record_iv_length; 3411 MACAlgorithm mac_algorithm; 3412 uint8 mac_length; 3413 uint8 mac_key_length; 3414 CompressionMethod compression_algorithm; 3415 opaque master_secret[48]; 3416 opaque client_random[32]; 3417 opaque server_random[32]; 3418 } SecurityParameters; 3420 A.7. Changes to RFC 4492 3422 RFC 4492 [TLSECC] adds Elliptic Curve cipher suites to TLS. This 3423 document changes some of the structures used in that document. This 3424 section details the required changes for implementors of both RFC 3425 4492 and TLS 1.2. Implementors of TLS 1.2 who are not implementing 3426 RFC 4492 do not need to read this section. 3428 This document adds a "signature_algorithm" field to the digitally- 3429 signed element in order to identify the signature and digest 3430 algorithms used to create a signature. This change applies to digital 3431 signatures formed using ECDSA as well, thus allowing ECDSA signatures 3432 to be used and digest algorithms other than SHA-1, provided such use 3433 is compatible with the certificate and any restrictions imposed by 3434 future revisions of [PKIX]. 3436 As described in Sections 7.4.2 and 7.4.6, the restrictions on the 3437 signature algorithms used to sign certificates are no longer tied to 3438 the cipher suite (when used by the server) or the 3439 ClientCertificateType (when used by the client). Thus, the 3440 restrictions on the algorithm used to sign certificates specified in 3441 Sections 2 and 3 of RFC 4492 are also relaxed. As in this document 3442 the restrictions on the keys in the end-entity certificate remain. 3444 Appendix B. Glossary 3446 Advanced Encryption Standard (AES) 3447 AES is a widely used symmetric encryption algorithm. AES is a 3448 block cipher with a 128, 192, or 256 bit keys and a 16 byte block 3449 size. [AES] TLS currently only supports the 128 and 256 bit key 3450 sizes. 3452 application protocol 3453 An application protocol is a protocol that normally layers 3454 directly on top of the transport layer (e.g., TCP/IP). Examples 3455 include HTTP, TELNET, FTP, and SMTP. 3457 asymmetric cipher 3458 See public key cryptography. 3460 authenticated encryption with additional data (AEAD) 3461 A symmetric encryption algorithm that simultaneously provides 3462 confidentiality and message integrity. 3464 authentication 3465 Authentication is the ability of one entity to determine the 3466 identity of another entity. 3468 block cipher 3469 A block cipher is an algorithm that operates on plaintext in 3470 groups of bits, called blocks. 64 bits is a common block size. 3472 bulk cipher 3473 A symmetric encryption algorithm used to encrypt large quantities 3474 of data. 3476 cipher block chaining (CBC) 3477 CBC is a mode in which every plaintext block encrypted with a 3478 block cipher is first exclusive-ORed with the previous ciphertext 3479 block (or, in the case of the first block, with the initialization 3480 vector). For decryption, every block is first decrypted, then 3481 exclusive-ORed with the previous ciphertext block (or IV). 3483 certificate 3484 As part of the X.509 protocol (a.k.a. ISO Authentication 3485 framework), certificates are assigned by a trusted Certificate 3486 Authority and provide a strong binding between a party's identity 3487 or some other attributes and its public key. 3489 client 3490 The application entity that initiates a TLS connection to a 3491 server. This may or may not imply that the client initiated the 3492 underlying transport connection. The primary operational 3493 difference between the server and client is that the server is 3494 generally authenticated, while the client is only optionally 3495 authenticated. 3497 client write key 3498 The key used to encrypt data written by the client. 3500 client write MAC key 3501 The secret data used to authenticate data written by the client. 3503 connection 3504 A connection is a transport (in the OSI layering model definition) 3505 that provides a suitable type of service. For TLS, such 3506 connections are peer-to-peer relationships. The connections are 3507 transient. Every connection is associated with one session. 3509 Data Encryption Standard 3510 DES is a very widely used symmetric encryption algorithm. DES is a 3511 block cipher with a 56 bit key and an 8 byte block size. Note that 3512 in TLS, for key generation purposes, DES is treated as having an 8 3513 byte key length (64 bits), but it still only provides 56 bits of 3514 protection. (The low bit of each key byte is presumed to be set to 3515 produce odd parity in that key byte.) DES can also be operated in 3516 a mode where three independent keys and three encryptions are used 3517 for each block of data; this uses 168 bits of key (24 bytes in the 3518 TLS key generation method) and provides the equivalent of 112 bits 3519 of security. [DES], [3DES] 3521 Digital Signature Standard (DSS) 3522 A standard for digital signing, including the Digital Signing 3523 Algorithm, approved by the National Institute of Standards and 3524 Technology, defined in NIST FIPS PUB 186, "Digital Signature 3525 Standard", published May, 1994 by the U.S. Dept. of Commerce. 3526 [DSS] 3528 digital signatures 3529 Digital signatures utilize public key cryptography and one-way 3530 hash functions to produce a signature of the data that can be 3531 authenticated, and is difficult to forge or repudiate. 3533 handshake 3534 An initial negotiation between client and server that establishes 3535 the parameters of their transactions. 3537 Initialization Vector (IV) 3538 When a block cipher is used in CBC mode, the initialization vector 3539 is exclusive-ORed with the first plaintext block prior to 3540 encryption. 3542 Message Authentication Code (MAC) 3543 A Message Authentication Code is a one-way hash computed from a 3544 message and some secret data. It is difficult to forge without 3545 knowing the secret data. Its purpose is to detect if the message 3546 has been altered. 3548 master secret 3549 Secure secret data used for generating encryption keys, MAC 3550 secrets, and IVs. 3552 MD5 3553 MD5 is a secure hashing function that converts an arbitrarily long 3554 data stream into a hash of fixed size (16 bytes). [MD5] 3556 public key cryptography 3557 A class of cryptographic techniques employing two-key ciphers. 3558 Messages encrypted with the public key can only be decrypted with 3559 the associated private key. Conversely, messages signed with the 3560 private key can be verified with the public key. 3562 one-way hash function 3563 A one-way transformation that converts an arbitrary amount of data 3564 into a fixed-length hash. It is computationally hard to reverse 3565 the transformation or to find collisions. MD5 and SHA are examples 3566 of one-way hash functions. 3568 RC4 3569 A stream cipher invented by Ron Rivest. A compatible cipher is 3570 described in [SCH]. 3572 RSA 3573 A very widely used public-key algorithm that can be used for 3574 either encryption or digital signing. [RSA] 3576 server 3577 The server is the application entity that responds to requests for 3578 connections from clients. See also under client. 3580 session 3581 A TLS session is an association between a client and a server. 3582 Sessions are created by the handshake protocol. Sessions define a 3583 set of cryptographic security parameters that can be shared among 3584 multiple connections. Sessions are used to avoid the expensive 3585 negotiation of new security parameters for each connection. 3587 session identifier 3588 A session identifier is a value generated by a server that 3589 identifies a particular session. 3591 server write key 3592 The key used to encrypt data written by the server. 3594 server write MAC key 3595 The secret data used to authenticate data written by the server. 3597 SHA 3598 The Secure Hash Algorithm is defined in FIPS PUB 180-2. It 3599 produces a 20-byte output. Note that all references to SHA 3600 actually use the modified SHA-1 algorithm. [SHA] 3602 SHA-256 3603 The 256-bit Secure Hash Algorithm is defined in FIPS PUB 180-2. It 3604 produces a 32-byte output. 3606 SSL 3607 Netscape's Secure Socket Layer protocol [SSL3]. TLS is based on 3608 SSL Version 3.0 3610 stream cipher 3611 An encryption algorithm that converts a key into a 3612 cryptographically strong keystream, which is then exclusive-ORed 3613 with the plaintext. 3615 symmetric cipher 3616 See bulk cipher. 3618 Transport Layer Security (TLS) 3619 This protocol; also, the Transport Layer Security working group of 3620 the Internet Engineering Task Force (IETF). See "Comments" at the 3621 end of this document. 3623 Appendix C. Cipher Suite Definitions 3625 Cipher Suite Key Cipher Mac 3626 Exchange 3628 TLS_NULL_WITH_NULL_NULL NULL NULL NULL 3629 TLS_RSA_WITH_NULL_MD5 RSA NULL MD5 3630 TLS_RSA_WITH_NULL_SHA RSA NULL SHA 3631 TLS_RSA_WITH_NULL_SHA256 RSA NULL SHA256 3632 TLS_RSA_WITH_RC4_128_MD5 RSA RC4_128 MD5 3633 TLS_RSA_WITH_RC4_128_SHA RSA RC4_128 SHA 3634 TLS_RSA_WITH_3DES_EDE_CBC_SHA RSA 3DES_EDE_CBC SHA 3635 TLS_RSA_WITH_AES_128_CBC_SHA RSA AES_128_CBC SHA 3636 TLS_RSA_WITH_AES_256_CBC_SHA RSA AES_256_CBC SHA 3637 TLS_RSA_WITH_AES_128_CBC_SHA256 RSA AES_128_CBC SHA256 3638 TLS_RSA_WITH_AES_256_CBC_SHA256 RSA AES_256_CBC SHA256 3639 TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA DH_DSS 3DES_EDE_CBC SHA 3640 TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA DH_RSA 3DES_EDE_CBC SHA 3641 TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE_DSS 3DES_EDE_CBC SHA 3642 TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE_RSA 3DES_EDE_CBC SHA 3643 TLS_DH_anon_WITH_RC4_128_MD5 DH_anon RC4_128 MD5 3644 TLS_DH_anon_WITH_3DES_EDE_CBC_SHA DH_anon 3DES_EDE_CBC SHA 3645 TLS_DH_DSS_WITH_AES_128_CBC_SHA DH_DSS AES_128_CBC SHA 3646 TLS_DH_RSA_WITH_AES_128_CBC_SHA DH_RSA AES_128_CBC SHA 3647 TLS_DHE_DSS_WITH_AES_128_CBC_SHA DHE_DSS AES_128_CBC SHA 3648 TLS_DHE_RSA_WITH_AES_128_CBC_SHA DHE_RSA AES_128_CBC SHA 3649 TLS_DH_anon_WITH_AES_128_CBC_SHA DH_anon AES_128_CBC SHA 3650 TLS_DH_DSS_WITH_AES_256_CBC_SHA DH_DSS AES_256_CBC SHA 3651 TLS_DH_RSA_WITH_AES_256_CBC_SHA DH_RSA AES_256_CBC SHA 3652 TLS_DHE_DSS_WITH_AES_256_CBC_SHA DHE_DSS AES_256_CBC SHA 3653 TLS_DHE_RSA_WITH_AES_256_CBC_SHA DHE_RSA AES_256_CBC SHA 3654 TLS_DH_anon_WITH_AES_256_CBC_SHA DH_anon AES_256_CBC SHA 3655 TLS_DH_DSS_WITH_AES_128_CBC_SHA256 DH_DSS AES_128_CBC SHA256 3656 TLS_DH_RSA_WITH_AES_128_CBC_SHA256 DH_RSA AES_128_CBC SHA256 3657 TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 DHE_DSS AES_128_CBC SHA256 3658 TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 DHE_RSA AES_128_CBC SHA256 3659 TLS_DH_anon_WITH_AES_128_CBC_SHA256 DH_anon AES_128_CBC SHA256 3660 TLS_DH_DSS_WITH_AES_256_CBC_SHA256 DH_DSS AES_256_CBC SHA256 3661 TLS_DH_RSA_WITH_AES_256_CBC_SHA256 DH_RSA AES_256_CBC SHA256 3662 TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 DHE_DSS AES_256_CBC SHA256 3663 TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 DHE_RSA AES_256_CBC SHA256 3664 TLS_DH_anon_WITH_AES_256_CBC_SHA256 DH_anon AES_256_CBC SHA256 3666 Key Expanded IV Block 3667 Cipher Type Material Key Material Size Size 3669 NULL Stream 0 0 0 N/A 3670 RC4_128 Stream 16 16 0 N/A 3671 3DES_EDE_CBC Block 24 24 8 8 3672 AES_128_CBC Block 16 16 16 16 3673 AES_256_CBC Block 32 32 16 16 3675 MAC Algorithm mac_length mac_key_length 3677 NULL N/A 0 0 3678 MD5 HMAC-MD5 16 16 3679 SHA HMAC-SHA1 20 20 3680 SHA256 HMAC-SHA256 32 32 3682 Type 3683 Indicates whether this is a stream cipher or a block cipher 3684 running in CBC mode. 3686 Key Material 3687 The number of bytes from the key_block that are used for 3688 generating the write keys. 3690 Expanded Key Material 3691 The number of bytes actually fed into the encryption algorithm. 3693 IV Size 3694 The amount of data needed to be generated for the initialization 3695 vector. Zero for stream ciphers; equal to the block size for block 3696 ciphers (this is equal to SecurityParameters.record_iv_length). 3698 Block Size 3699 The amount of data a block cipher enciphers in one chunk; a block 3700 cipher running in CBC mode can only encrypt an even multiple of 3701 its block size. 3703 Appendix D. Implementation Notes 3705 The TLS protocol cannot prevent many common security mistakes. This 3706 section provides several recommendations to assist implementors. 3708 D.1 Random Number Generation and Seeding 3710 TLS requires a cryptographically secure pseudorandom number generator 3711 (PRNG). Care must be taken in designing and seeding PRNGs. PRNGs 3712 based on secure hash operations, most notably SHA-1, are acceptable, 3713 but cannot provide more security than the size of the random number 3714 generator state. 3716 To estimate the amount of seed material being produced, add the 3717 number of bits of unpredictable information in each seed byte. For 3718 example, keystroke timing values taken from a PC compatible's 18.2 Hz 3719 timer provide 1 or 2 secure bits each, even though the total size of 3720 the counter value is 16 bits or more. Seeding a 128-bit PRNG would 3721 thus require approximately 100 such timer values. 3723 [RANDOM] provides guidance on the generation of random values. 3725 D.2 Certificates and Authentication 3727 Implementations are responsible for verifying the integrity of 3728 certificates and should generally support certificate revocation 3729 messages. Certificates should always be verified to ensure proper 3730 signing by a trusted Certificate Authority (CA). The selection and 3731 addition of trusted CAs should be done very carefully. Users should 3732 be able to view information about the certificate and root CA. 3734 D.3 Cipher Suites 3736 TLS supports a range of key sizes and security levels, including some 3737 that provide no or minimal security. A proper implementation will 3738 probably not support many cipher suites. For instance, anonymous 3739 Diffie-Hellman is strongly discouraged because it cannot prevent man- 3740 in-the-middle attacks. Applications should also enforce minimum and 3741 maximum key sizes. For example, certificate chains containing 512-bit 3742 RSA keys or signatures are not appropriate for high-security 3743 applications. 3745 D.4 Implementation Pitfalls 3747 Implementation experience has shown that certain parts of earlier TLS 3748 specifications are not easy to understand, and have been a source of 3749 interoperability and security problems. Many of these areas have been 3750 clarified in this document, but this appendix contains a short list 3751 of the most important things that require special attention from 3752 implementors. 3754 TLS protocol issues: 3756 - Do you correctly handle handshake messages that are fragmented 3757 to multiple TLS records (see Section 6.2.1)? Including corner 3758 cases like a ClientHello that is split to several small 3759 fragments? Do you fragment handshake messages that exceed the 3760 maximum fragment size? In particular, the certificate and 3761 certificate request handshake messages can be large enough to 3762 require fragmentation. 3764 - Do you ignore the TLS record layer version number in all TLS 3765 records before ServerHello (see Appendix E.1)? 3767 - Do you handle TLS extensions in ClientHello correctly, 3768 including omitting the extensions field completely? 3770 - Do you support renegotiation, both client and server initiated? 3771 While renegotiation is an optional feature, supporting 3772 it is highly recommended. 3774 - When the server has requested a client certificate, but no 3775 suitable certificate is available, do you correctly send 3776 an empty Certificate message, instead of omitting the whole 3777 message (see Section 7.4.6)? 3779 Cryptographic details: 3781 - In RSA-encrypted Premaster Secret, do you correctly send and 3782 verify the version number? When an error is encountered, do 3783 you continue the handshake to avoid the Bleichenbacher 3784 attack (see Section 7.4.7.1)? 3786 - What countermeasures do you use to prevent timing attacks against 3787 RSA decryption and signing operations (see Section 7.4.7.1)? 3789 - When verifying RSA signatures, do you accept both NULL and 3790 missing parameters (see Section 4.7)? Do you verify that the 3791 RSA padding doesn't have additional data after the hash value? 3792 [FI06] 3794 - When using Diffie-Hellman key exchange, do you correctly strip 3795 leading zero bytes from the negotiated key (see Section 8.1.2)? 3797 - Does your TLS client check that the Diffie-Hellman parameters 3798 sent by the server are acceptable (see Section F.1.1.3)? 3800 - How do you generate unpredictable IVs for CBC mode ciphers 3801 (see Section 6.2.3.2)? 3803 - Do you accept long CBC mode padding (up to 255 bytes; see 3804 Section 6.2.3.2)? 3806 - How do you address CBC mode timing attacks (Section 6.2.3.2)? 3808 - Do you use a strong and, most importantly, properly seeded 3809 random number generator (see Appendix D.1) for generating the 3810 premaster secret (for RSA key exchange), Diffie-Hellman private 3811 values, the DSA "k" parameter, and other security-critical 3812 values? 3814 Appendix E. Backward Compatibility 3816 E.1 Compatibility with TLS 1.0/1.1 and SSL 3.0 3818 Since there are various versions of TLS (1.0, 1.1, 1.2, and any 3819 future versions) and SSL (2.0 and 3.0), means are needed to negotiate 3820 the specific protocol version to use. The TLS protocol provides a 3821 built-in mechanism for version negotiation so as not to bother other 3822 protocol components with the complexities of version selection. 3824 TLS versions 1.0, 1.1, and 1.2, and SSL 3.0 are very similar, and use 3825 compatible ClientHello messages; thus, supporting all of them is 3826 relatively easy. Similarly, servers can easily handle clients trying 3827 to use future versions of TLS as long as the ClientHello format 3828 remains compatible, and the client support the highest protocol 3829 version available in the server. 3831 A TLS 1.2 client who wishes to negotiate with such older servers will 3832 send a normal TLS 1.2 ClientHello, containing { 3, 3 } (TLS 1.2) in 3833 ClientHello.client_version. If the server does not support this 3834 version, it will respond with ServerHello containing an older version 3835 number. If the client agrees to use this version, the negotiation 3836 will proceed as appropriate for the negotiated protocol. 3838 If the version chosen by the server is not supported by the client 3839 (or not acceptable), the client MUST send a "protocol_version" alert 3840 message and close the connection. 3842 If a TLS server receives a ClientHello containing a version number 3843 greater than the highest version supported by the server, it MUST 3844 reply according to the highest version supported by the server. 3846 A TLS server can also receive a ClientHello containing version number 3847 smaller than the highest supported version. If the server wishes to 3848 negotiate with old clients, it will proceed as appropriate for the 3849 highest version supported by the server that is not greater than 3850 ClientHello.client_version. For example, if the server supports TLS 3851 1.0, 1.1, and 1.2, and client_version is TLS 1.0, the server will 3852 proceed with a TLS 1.0 ServerHello. If server supports (or is willing 3853 to use) only versions greater than client_version, it MUST send a 3854 "protocol_version" alert message and close the connection. 3856 Whenever a client already knows the highest protocol known to a 3857 server (for example, when resuming a session), it SHOULD initiate the 3858 connection in that native protocol. 3860 Note: some server implementations are known to implement version 3861 negotiation incorrectly. For example, there are buggy TLS 1.0 servers 3862 that simply close the connection when the client offers a version 3863 newer than TLS 1.0. Also, it is known that some servers will refuse 3864 connection if any TLS extensions are included in ClientHello. 3865 Interoperability with such buggy servers is a complex topic beyond 3866 the scope of this document, and may require multiple connection 3867 attempts by the client. 3869 Earlier versions of the TLS specification were not fully clear on 3870 what the record layer version number (TLSPlaintext.version) should 3871 contain when sending ClientHello (i.e., before it is known which 3872 version of the protocol will be employed). Thus, TLS servers 3873 compliant with this specification MUST accept any value {03,XX} as 3874 the record layer version number for ClientHello. 3876 TLS clients that wish to negotiate with older servers MAY send any 3877 value {03,XX} as the record layer version number. Typical values 3878 would be {03,00}, the lowest version number supported by the client, 3879 and the value of ClientHello.client_version. No single value will 3880 guarantee interoperability with all old servers, but this is a 3881 complex topic beyond the scope of this document. 3883 E.2 Compatibility with SSL 2.0 3885 TLS 1.2 clients that wish to support SSL 2.0 servers MUST send 3886 version 2.0 CLIENT-HELLO messages defined in [SSL2]. The message MUST 3887 contain the same version number as would be used for ordinary 3888 ClientHello, and MUST encode the supported TLS cipher suites in the 3889 CIPHER-SPECS-DATA field as described below. 3891 Warning: The ability to send version 2.0 CLIENT-HELLO messages will 3892 be phased out with all due haste, since the newer ClientHello format 3893 provides better mechanisms for moving to newer versions and 3894 negotiating extensions. TLS 1.2 clients SHOULD NOT support SSL 2.0. 3896 However, even TLS servers that do not support SSL 2.0 MAY accept 3897 version 2.0 CLIENT-HELLO messages. The message is presented below in 3898 sufficient detail for TLS server implementors; the true definition is 3899 still assumed to be [SSL2]. 3901 For negotiation purposes, 2.0 CLIENT-HELLO is interpreted the same 3902 way as a ClientHello with a "null" compression method and no 3903 extensions. Note that this message MUST be sent directly on the wire, 3904 not wrapped as a TLS record. For the purposes of calculating Finished 3905 and CertificateVerify, the msg_length field is not considered to be a 3906 part of the handshake message. 3908 uint8 V2CipherSpec[3]; 3909 struct { 3910 uint16 msg_length; 3911 uint8 msg_type; 3912 Version version; 3913 uint16 cipher_spec_length; 3914 uint16 session_id_length; 3915 uint16 challenge_length; 3916 V2CipherSpec cipher_specs[V2ClientHello.cipher_spec_length]; 3917 opaque session_id[V2ClientHello.session_id_length]; 3918 opaque challenge[V2ClientHello.challenge_length; 3919 } V2ClientHello; 3921 msg_length 3922 The highest bit MUST be 1; the remaining bits contain the length 3923 of the following data in bytes. 3925 msg_type 3926 This field, in conjunction with the version field, identifies a 3927 version 2 client hello message. The value MUST be one (1). 3929 version 3930 Equal to ClientHello.client_version. 3932 cipher_spec_length 3933 This field is the total length of the field cipher_specs. It 3934 cannot be zero and MUST be a multiple of the V2CipherSpec length 3935 (3). 3937 session_id_length 3938 This field MUST have a value of zero for a client that claims to 3939 support TLS 1.2. 3941 challenge_length 3942 The length in bytes of the client's challenge to the server to 3943 authenticate itself. Historically, permissible values are between 3944 16 and 32 bytes inclusive. When using the SSLv2 backward 3945 compatible handshake the client SHOULD use a 32 byte challenge. 3947 cipher_specs 3948 This is a list of all CipherSpecs the client is willing and able 3949 to use. In addition to the 2.0 cipher specs defined in [SSL2], 3950 this includes the TLS cipher suites normally sent in 3951 ClientHello.cipher_suites, each cipher suite prefixed by a zero 3952 byte. For example, TLS cipher suite {0x00,0x0A} would be sent as 3953 {0x00,0x00,0x0A}. 3955 session_id 3956 This field MUST be empty. 3958 challenge 3959 Corresponds to ClientHello.random. If the challenge length is less 3960 than 32, the TLS server will pad the data with leading (note: not 3961 trailing) zero bytes to make it 32 bytes long. 3963 Note: Requests to resume a TLS session MUST use a TLS client hello. 3965 E.3. Avoiding Man-in-the-Middle Version Rollback 3967 When TLS clients fall back to Version 2.0 compatibility mode, they 3968 MUST use special PKCS#1 block formatting. This is done so that TLS 3969 servers will reject Version 2.0 sessions with TLS-capable clients. 3971 When a client negotiates SSL 2.0 but also supports TLS, it MUST set 3972 the right-hand (least-significant) 8 random bytes of the PKCS padding 3973 (not including the terminal null of the padding) for the RSA 3974 encryption of the ENCRYPTED-KEY-DATA field of the CLIENT-MASTER-KEY 3975 to 0x03 (the other padding bytes are random). 3977 When a TLS-capable server negotiates SSL 2.0 it SHOULD, after 3978 decrypting the ENCRYPTED-KEY-DATA field, check that these eight 3979 padding bytes are 0x03. If they are not, the server SHOULD generate a 3980 random value for SECRET-KEY-DATA, and continue the handshake (which 3981 will eventually fail since the keys will not match). Note that 3982 reporting the error situation to the client could make the server 3983 vulnerable to attacks described in [BLEI]. 3985 Appendix F. Security Analysis 3987 The TLS protocol is designed to establish a secure connection between 3988 a client and a server communicating over an insecure channel. This 3989 document makes several traditional assumptions, including that 3990 attackers have substantial computational resources and cannot obtain 3991 secret information from sources outside the protocol. Attackers are 3992 assumed to have the ability to capture, modify, delete, replay, and 3993 otherwise tamper with messages sent over the communication channel. 3994 This appendix outlines how TLS has been designed to resist a variety 3995 of attacks. 3997 F.1. Handshake Protocol 3999 The handshake protocol is responsible for selecting a CipherSpec and 4000 generating a Master Secret, which together comprise the primary 4001 cryptographic parameters associated with a secure session. The 4002 handshake protocol can also optionally authenticate parties who have 4003 certificates signed by a trusted certificate authority. 4005 F.1.1. Authentication and Key Exchange 4007 TLS supports three authentication modes: authentication of both 4008 parties, server authentication with an unauthenticated client, and 4009 total anonymity. Whenever the server is authenticated, the channel is 4010 secure against man-in-the-middle attacks, but completely anonymous 4011 sessions are inherently vulnerable to such attacks. Anonymous 4012 servers cannot authenticate clients. If the server is authenticated, 4013 its certificate message must provide a valid certificate chain 4014 leading to an acceptable certificate authority. Similarly, 4015 authenticated clients must supply an acceptable certificate to the 4016 server. Each party is responsible for verifying that the other's 4017 certificate is valid and has not expired or been revoked. 4019 The general goal of the key exchange process is to create a 4020 pre_master_secret known to the communicating parties and not to 4021 attackers. The pre_master_secret will be used to generate the 4022 master_secret (see Section 8.1). The master_secret is required to 4023 generate the finished messages, encryption keys, and MAC keys (see 4024 Sections 7.4.9 and 6.3). By sending a correct finished message, 4025 parties thus prove that they know the correct pre_master_secret. 4027 F.1.1.1. Anonymous Key Exchange 4029 Completely anonymous sessions can be established using Diffie-Hellman 4030 for key exchange. The server's public parameters are contained in the 4031 server key exchange message and the client's are sent in the client 4032 key exchange message. Eavesdroppers who do not know the private 4033 values should not be able to find the Diffie-Hellman result (i.e. the 4034 pre_master_secret). 4036 Warning: Completely anonymous connections only provide protection 4037 against passive eavesdropping. Unless an independent tamper-proof 4038 channel is used to verify that the finished messages were not 4039 replaced by an attacker, server authentication is required in 4040 environments where active man-in-the-middle attacks are a concern. 4042 F.1.1.2. RSA Key Exchange and Authentication 4044 With RSA, key exchange and server authentication are combined. The 4045 public key is contained in the server's certificate. Note that 4046 compromise of the server's static RSA key results in a loss of 4047 confidentiality for all sessions protected under that static key. TLS 4048 users desiring Perfect Forward Secrecy should use DHE cipher suites. 4049 The damage done by exposure of a private key can be limited by 4050 changing one's private key (and certificate) frequently. 4052 After verifying the server's certificate, the client encrypts a 4053 pre_master_secret with the server's public key. By successfully 4054 decoding the pre_master_secret and producing a correct finished 4055 message, the server demonstrates that it knows the private key 4056 corresponding to the server certificate. 4058 When RSA is used for key exchange, clients are authenticated using 4059 the certificate verify message (see Section 7.4.8). The client signs 4060 a value derived from all preceding handshake messages. These 4061 handshake messages include the server certificate, which binds the 4062 signature to the server, and ServerHello.random, which binds the 4063 signature to the current handshake process. 4065 F.1.1.3. Diffie-Hellman Key Exchange with Authentication 4067 When Diffie-Hellman key exchange is used, the server can either 4068 supply a certificate containing fixed Diffie-Hellman parameters or 4069 use the server key exchange message to send a set of temporary 4070 Diffie-Hellman parameters signed with a DSS or RSA certificate. 4071 Temporary parameters are hashed with the hello.random values before 4072 signing to ensure that attackers do not replay old parameters. In 4073 either case, the client can verify the certificate or signature to 4074 ensure that the parameters belong to the server. 4076 If the client has a certificate containing fixed Diffie-Hellman 4077 parameters, its certificate contains the information required to 4078 complete the key exchange. Note that in this case the client and 4079 server will generate the same Diffie-Hellman result (i.e., 4080 pre_master_secret) every time they communicate. To prevent the 4081 pre_master_secret from staying in memory any longer than necessary, 4082 it should be converted into the master_secret as soon as possible. 4083 Client Diffie-Hellman parameters must be compatible with those 4084 supplied by the server for the key exchange to work. 4086 If the client has a standard DSS or RSA certificate or is 4087 unauthenticated, it sends a set of temporary parameters to the server 4088 in the client key exchange message, then optionally uses a 4089 certificate verify message to authenticate itself. 4091 If the same DH keypair is to be used for multiple handshakes, either 4092 because the client or server has a certificate containing a fixed DH 4093 keypair or because the server is reusing DH keys, care must be taken 4094 to prevent small subgroup attacks. Implementations SHOULD follow the 4095 guidelines found in [SUBGROUP]. 4097 Small subgroup attacks are most easily avoided by using one of the 4098 DHE cipher suites and generating a fresh DH private key (X) for each 4099 handshake. If a suitable base (such as 2) is chosen, g^X mod p can be 4100 computed very quickly, therefore the performance cost is minimized. 4101 Additionally, using a fresh key for each handshake provides Perfect 4102 Forward Secrecy. Implementations SHOULD generate a new X for each 4103 handshake when using DHE cipher suites. 4105 Because TLS allows the server to provide arbitrary DH groups, the 4106 client should verify that the DH group is of suitable size as defined 4107 by local policy. The client SHOULD also verify that the DH public 4108 exponent appears to be of adequate size. [KEYSIZ] provides a useful 4109 guide to the strength of various group sizes. The server MAY choose 4110 to assist the client by providing a known group, such as those 4111 defined in [IKEALG] or [MODP]. These can be verified by simple 4112 comparison. 4114 F.1.2. Version Rollback Attacks 4116 Because TLS includes substantial improvements over SSL Version 2.0, 4117 attackers may try to make TLS-capable clients and servers fall back 4118 to Version 2.0. This attack can occur if (and only if) two TLS- 4119 capable parties use an SSL 2.0 handshake. 4121 Although the solution using non-random PKCS #1 block type 2 message 4122 padding is inelegant, it provides a reasonably secure way for Version 4123 3.0 servers to detect the attack. This solution is not secure against 4124 attackers who can brute force the key and substitute a new ENCRYPTED- 4125 KEY-DATA message containing the same key (but with normal padding) 4126 before the application specified wait threshold has expired. Altering 4127 the padding of the least significant 8 bytes of the PKCS padding does 4128 not impact security for the size of the signed hashes and RSA key 4129 lengths used in the protocol, since this is essentially equivalent to 4130 increasing the input block size by 8 bytes. 4132 F.1.3. Detecting Attacks Against the Handshake Protocol 4134 An attacker might try to influence the handshake exchange to make the 4135 parties select different encryption algorithms than they would 4136 normally chooses. 4138 For this attack, an attacker must actively change one or more 4139 handshake messages. If this occurs, the client and server will 4140 compute different values for the handshake message hashes. As a 4141 result, the parties will not accept each others' finished messages. 4142 Without the master_secret, the attacker cannot repair the finished 4143 messages, so the attack will be discovered. 4145 F.1.4. Resuming Sessions 4147 When a connection is established by resuming a session, new 4148 ClientHello.random and ServerHello.random values are hashed with the 4149 session's master_secret. Provided that the master_secret has not been 4150 compromised and that the secure hash operations used to produce the 4151 encryption keys and MAC keys are secure, the connection should be 4152 secure and effectively independent from previous connections. 4153 Attackers cannot use known encryption keys or MAC secrets to 4154 compromise the master_secret without breaking the secure hash 4155 operations. 4157 Sessions cannot be resumed unless both the client and server agree. 4158 If either party suspects that the session may have been compromised, 4159 or that certificates may have expired or been revoked, it should 4160 force a full handshake. An upper limit of 24 hours is suggested for 4161 session ID lifetimes, since an attacker who obtains a master_secret 4162 may be able to impersonate the compromised party until the 4163 corresponding session ID is retired. Applications that may be run in 4164 relatively insecure environments should not write session IDs to 4165 stable storage. 4167 F.2. Protecting Application Data 4169 The master_secret is hashed with the ClientHello.random and 4170 ServerHello.random to produce unique data encryption keys and MAC 4171 secrets for each connection. 4173 Outgoing data is protected with a MAC before transmission. To prevent 4174 message replay or modification attacks, the MAC is computed from the 4175 MAC key, the sequence number, the message length, the message 4176 contents, and two fixed character strings. The message type field is 4177 necessary to ensure that messages intended for one TLS Record Layer 4178 client are not redirected to another. The sequence number ensures 4179 that attempts to delete or reorder messages will be detected. Since 4180 sequence numbers are 64 bits long, they should never overflow. 4181 Messages from one party cannot be inserted into the other's output, 4182 since they use independent MAC keys. Similarly, the server-write and 4183 client-write keys are independent, so stream cipher keys are used 4184 only once. 4186 If an attacker does break an encryption key, all messages encrypted 4187 with it can be read. Similarly, compromise of a MAC key can make 4188 message modification attacks possible. Because MACs are also 4189 encrypted, message-alteration attacks generally require breaking the 4190 encryption algorithm as well as the MAC. 4192 Note: MAC keys may be larger than encryption keys, so messages can 4193 remain tamper resistant even if encryption keys are broken. 4195 F.3. Explicit IVs 4197 [CBCATT] describes a chosen plaintext attack on TLS that depends on 4198 knowing the IV for a record. Previous versions of TLS [TLS1.0] used 4199 the CBC residue of the previous record as the IV and therefore 4200 enabled this attack. This version uses an explicit IV in order to 4201 protect against this attack. 4203 F.4. Security of Composite Cipher Modes 4205 TLS secures transmitted application data via the use of symmetric 4206 encryption and authentication functions defined in the negotiated 4207 cipher suite. The objective is to protect both the integrity and 4208 confidentiality of the transmitted data from malicious actions by 4209 active attackers in the network. It turns out that the order in 4210 which encryption and authentication functions are applied to the data 4211 plays an important role for achieving this goal [ENCAUTH]. 4213 The most robust method, called encrypt-then-authenticate, first 4214 applies encryption to the data and then applies a MAC to the 4215 ciphertext. This method ensures that the integrity and 4216 confidentiality goals are obtained with ANY pair of encryption and 4217 MAC functions, provided that the former is secure against chosen 4218 plaintext attacks and that the MAC is secure against chosen-message 4219 attacks. TLS uses another method, called authenticate-then-encrypt, 4220 in which first a MAC is computed on the plaintext and then the 4221 concatenation of plaintext and MAC is encrypted. This method has 4222 been proven secure for CERTAIN combinations of encryption functions 4223 and MAC functions, but it is not guaranteed to be secure in general. 4224 In particular, it has been shown that there exist perfectly secure 4225 encryption functions (secure even in the information-theoretic sense) 4226 that combined with any secure MAC function, fail to provide the 4227 confidentiality goal against an active attack. Therefore, new cipher 4228 suites and operation modes adopted into TLS need to be analyzed under 4229 the authenticate-then-encrypt method to verify that they achieve the 4230 stated integrity and confidentiality goals. 4232 Currently, the security of the authenticate-then-encrypt method has 4233 been proven for some important cases. One is the case of stream 4234 ciphers in which a computationally unpredictable pad of the length of 4235 the message, plus the length of the MAC tag, is produced using a 4236 pseudo-random generator and this pad is xor-ed with the concatenation 4237 of plaintext and MAC tag. The other is the case of CBC mode using a 4238 secure block cipher. In this case, security can be shown if one 4239 applies one CBC encryption pass to the concatenation of plaintext and 4240 MAC and uses a new, independent, and unpredictable IV for each new 4241 pair of plaintext and MAC. In versions of TLS prior to 1.1, CBC mode 4242 was used properly EXCEPT that it used a predictable IV in the form of 4243 the last block of the previous ciphertext. This made TLS open to 4244 chosen plaintext attacks. This version of the protocol is immune to 4245 those attacks. For exact details in the encryption modes proven 4246 secure, see [ENCAUTH]. 4248 F.5 Denial of Service 4250 TLS is susceptible to a number of denial of service (DoS) attacks. 4251 In particular, an attacker who initiates a large number of TCP 4252 connections can cause a server to consume large amounts of CPU doing 4253 RSA decryption. However, because TLS is generally used over TCP, it 4254 is difficult for the attacker to hide his point of origin if proper 4255 TCP SYN randomization is used [SEQNUM] by the TCP stack. 4257 Because TLS runs over TCP, it is also susceptible to a number of 4258 denial of service attacks on individual connections. In particular, 4259 attackers can forge RSTs, thereby terminating connections, or forge 4260 partial TLS records, thereby causing the connection to stall. These 4261 attacks cannot in general be defended against by a TCP-using 4262 protocol. Implementors or users who are concerned with this class of 4263 attack should use IPsec AH [AH] or ESP [ESP]. 4265 F.6 Final Notes 4267 For TLS to be able to provide a secure connection, both the client 4268 and server systems, keys, and applications must be secure. In 4269 addition, the implementation must be free of security errors. 4271 The system is only as strong as the weakest key exchange and 4272 authentication algorithm supported, and only trustworthy 4273 cryptographic functions should be used. Short public keys and 4274 anonymous servers should be used with great caution. Implementations 4275 and users must be careful when deciding which certificates and 4276 certificate authorities are acceptable; a dishonest certificate 4277 authority can do tremendous damage. 4279 Changes in This Version 4280 [RFC Editor: Please delete this] 4282 - Added a new pitfall about fragmenting messages when necessary 4283 [Issue #71] 4285 - Added Updates: RFC 4492 [Issue #83] 4287 - Long CBC padding pitfall [Issue #73] 4289 - Fixed ProtocolVersion structure [Issue #79] 4291 - Cleaned up extensions text [Issue #78] 4293 - Clarified alerts some [Issue #85] 4295 - Added AES to the table in Appendix C [Issue #72] 4297 - Tightened up when signature_algorithms is used 4298 (it is now a MUST if you support other than SHA-1) 4299 and the interpretation when it is absent is also a MUST 4300 [Issue #67] 4302 - Cleaned up "cipher suite" so it's always two words outside 4303 of when it refers to the syntactic type [Issue #68] 4305 - Misc editorial. 4307 - Added support for SHA256 cipher suites 4309 - Clarified warning alert behavior and client certificate omission 4310 behavior [Issue #84] 4312 - Removed IDEA and DES entirely for documentation in a separate doc 4313 [Issue #64] 4315 - Changed the presentation language to allow fall-through to simplify 4316 some of the PDUs. 4318 - Cleaned up KeyExchangeAlgorithm ClientKeyExchange to use values 4319 that match Appendix C. 4321 - Changed digitally-signed to include SignatureAndHashAlgorithm 4322 (another simplification) 4324 - Considerations for RFC 4492 4326 Normative References 4328 [AES] National Institute of Standards and Technology, 4329 "Specification for the Advanced Encryption Standard (AES)" 4330 FIPS 197. November 26, 2001. 4332 [3DES] National Institute of Standards and Technology, 4333 "Recommendation for the Triple Data Encryption Algorithm 4334 (TDEA) Block Cipher", NIST Special Publication 800-67, May 4335 2004. 4337 [DES] National Institute of Standards and Technology, "Data 4338 Encryption Standard (DES)", FIPS PUB 46-3, October 1999. 4340 [DSS] NIST FIPS PUB 186-2, "Digital Signature Standard," National 4341 Institute of Standards and Technology, U.S. Department of 4342 Commerce, 2000. 4344 [HMAC] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 4345 Hashing for Message Authentication", RFC 2104, February 4346 1997. 4348 [MD5] Rivest, R., "The MD5 Message Digest Algorithm", RFC 1321, 4349 April 1992. 4351 [PKCS1] J. Jonsson, B. Kaliski, "Public-Key Cryptography Standards 4352 (PKCS) #1: RSA Cryptography Specifications Version 2.1", RFC 4353 3447, February 2003. 4355 [PKIX] Housley, R., Ford, W., Polk, W. and D. Solo, "Internet X.509 4356 Public Key Infrastructure Certificate and Certificate 4357 Revocation List (CRL) Profile", RFC 3280, April 2002. 4359 [SCH] B. Schneier. "Applied Cryptography: Protocols, Algorithms, 4360 and Source Code in C, 2nd ed.", Published by John Wiley & 4361 Sons, Inc. 1996. 4363 [SHA] NIST FIPS PUB 180-2, "Secure Hash Standard," National 4364 Institute of Standards and Technology, U.S. Department of 4365 Commerce., August 2001. 4367 [REQ] Bradner, S., "Key words for use in RFCs to Indicate 4368 Requirement Levels", BCP 14, RFC 2119, March 1997. 4370 [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an 4371 IANA Considerations Section in RFCs", BCP 25, RFC 2434, 4372 October 1998. 4374 Informative References 4376 [AEAD] Mcgrew, D., "Authenticated Encryption", July 2007, draft- 4377 mcgrew-auth-enc-05.txt. 4379 [AH] Kent, S., and Atkinson, R., "IP Authentication Header", RFC 4380 4302, December 2005. 4382 [BLEI] Bleichenbacher D., "Chosen Ciphertext Attacks against 4383 Protocols Based on RSA Encryption Standard PKCS #1" in 4384 Advances in Cryptology -- CRYPTO'98, LNCS vol. 1462, pages: 4385 1-12, 1998. 4387 [CBCATT] Moeller, B., "Security of CBC Ciphersuites in SSL/TLS: 4388 Problems and Countermeasures", 4389 http://www.openssl.org/~bodo/tls-cbc.txt. 4391 [CBCTIME] Canvel, B., Hiltgen, A., Vaudenay, S., and M. Vuagnoux, 4392 "Password Interception in a SSL/TLS Channel", Advances in 4393 Cryptology -- CRYPTO 2003, LNCS vol. 2729, 2003. 4395 [CCM] "NIST Special Publication 800-38C: The CCM Mode for 4396 Authentication and Confidentiality", 4397 http://csrc.nist.gov/publications/nistpubs/800-38C/ 4398 SP800-38C.pdf 4400 [DSS-3] NIST FIPS PUB 186-3 Draft, "Digital Signature Standard," 4401 National Institute of Standards and Technology, U.S. 4402 Department of Commerce, 2006. 4404 [ENCAUTH] Krawczyk, H., "The Order of Encryption and Authentication 4405 for Protecting Communications (Or: How Secure is SSL?)", 4406 Crypto 2001. 4408 [ESP] Kent, S., and Atkinson, R., "IP Encapsulating Security 4409 Payload (ESP)", RFC 4303, December 2005. 4411 [FI06] Hal Finney, "Bleichenbacher's RSA signature forgery based on 4412 implementation error", ietf-openpgp@imc.org mailing list, 27 4413 August 2006, http://www.imc.org/ietf-openpgp/mail- 4414 archive/msg14307.html. 4416 [GCM] "NIST Special Publication 800-38D DRAFT (June, 2007): 4417 Recommendation for Block Cipher Modes of Operation: 4418 Galois/Counter Mode (GCM) and GMAC" 4420 [IKEALG] Schiller, J., "Cryptographic Algorithms for Use in the 4421 Internet Key Exchange Version 2 (IKEv2)", RFC 4307, December 4422 2005. 4424 [KEYSIZ] Orman, H., and Hoffman, P., "Determining Strengths For 4425 Public Keys Used For Exchanging Symmetric Keys" RFC 3766, 4426 April 2004. 4428 [KPR03] Klima, V., Pokorny, O., Rosa, T., "Attacking RSA-based 4429 Sessions in SSL/TLS", http://eprint.iacr.org/2003/052/, 4430 March 2003. 4432 [MODP] Kivinen, T. and M. Kojo, "More Modular Exponential (MODP) 4433 Diffie-Hellman groups for Internet Key Exchange (IKE)", RFC 4434 3526, May 2003. 4436 [PKCS6] RSA Laboratories, "PKCS #6: RSA Extended Certificate Syntax 4437 Standard," version 1.5, November 1993. 4439 [PKCS7] RSA Laboratories, "PKCS #7: RSA Cryptographic Message Syntax 4440 Standard," version 1.5, November 1993. 4442 [RANDOM] Eastlake, D., 3rd, Schiller, J., and S. Crocker, "Randomness 4443 Requirements for Security", BCP 106, RFC 4086, June 2005. 4445 [RFC3749] Hollenbeck, S., "Transport Layer Security Protocol 4446 Compression Methods", RFC 3749, May 2004. 4448 [RFC4366] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J., 4449 Wright, T., "Transport Layer Security (TLS) Extensions", RFC 4450 4366, April 2006. 4452 [RSA] R. Rivest, A. Shamir, and L. M. Adleman, "A Method for 4453 Obtaining Digital Signatures and Public-Key Cryptosystems," 4454 Communications of the ACM, v. 21, n. 2, Feb 1978, pp. 4455 120-126. 4457 [SEQNUM] Bellovin. S., "Defending Against Sequence Number Attacks", 4458 RFC 1948, May 1996. 4460 [SSL2] Hickman, Kipp, "The SSL Protocol", Netscape Communications 4461 Corp., Feb 9, 1995. 4463 [SSL3] A. Freier, P. Karlton, and P. Kocher, "The SSL 3.0 4464 Protocol", Netscape Communications Corp., Nov 18, 1996. 4466 [SUBGROUP] Zuccherato, R., "Methods for Avoiding the "Small-Subgroup" 4467 Attacks on the Diffie-Hellman Key Agreement Method for 4468 S/MIME", RFC 2785, March 2000. 4470 [TCP] Postel, J., "Transmission Control Protocol," STD 7, RFC 793, 4471 September 1981. 4473 [TIMING] Boneh, D., Brumley, D., "Remote timing attacks are 4474 practical", USENIX Security Symposium 2003. 4476 [TLSAES] Chown, P., "Advanced Encryption Standard (AES) Ciphersuites 4477 for Transport Layer Security (TLS)", RFC 3268, June 2002. 4479 [TLSECC] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and 4480 Moeller, B., "Elliptic Curve Cryptography (ECC) Cipher 4481 Suites for Transport Layer Security (TLS)", RFC 4492, May 4482 2006. 4484 [TLSEXT] Eastlake, D.E., "Transport Layer Security (TLS) Extensions: 4485 Extension Definitions", January 2008, draft-ietf-tls- 4486 rfc4366-bis-01.txt. 4488 [TLSPGP] Mavrogiannopoulos, N., "Using OpenPGP keys for TLS 4489 authentication", RFC 5081, November 2007. 4491 [TLSPSK] Eronen, P., Tschofenig, H., "Pre-Shared Key Ciphersuites for 4492 Transport Layer Security (TLS)", RFC 4279, December 2005. 4494 [TLS1.0] Dierks, T., and C. Allen, "The TLS Protocol, Version 1.0", 4495 RFC 2246, January 1999. 4497 [TLS1.1] Dierks, T., and E. Rescorla, "The TLS Protocol, Version 4498 1.1", RFC 4346, April, 2006. 4500 [X501] ITU-T Recommendation X.501: Information Technology - Open 4501 Systems Interconnection - The Directory: Models, 1993. 4503 [XDR] Eisler, M., "External Data Representation Standard", RFC 4504 4506, May 2006. 4506 Credits 4508 Working Group Chairs 4510 Eric Rescorla 4511 EMail: ekr@networkresonance.com 4513 Pasi Eronen 4514 pasi.eronen@nokia.com 4516 Editors 4518 Tim Dierks Eric Rescorla 4519 Independent Network Resonance, Inc. 4520 EMail: tim@dierks.org EMail: ekr@networkresonance.com 4522 Other contributors 4524 Christopher Allen (co-editor of TLS 1.0) 4525 Alacrity Ventures 4526 ChristopherA@AlacrityManagement.com 4528 Martin Abadi 4529 University of California, Santa Cruz 4530 abadi@cs.ucsc.edu 4532 Steven M. Bellovin 4533 Columbia University 4534 smb@cs.columbia.edu 4536 Simon Blake-Wilson 4537 BCI 4538 EMail: sblakewilson@bcisse.com 4540 Ran Canetti 4541 IBM 4542 canetti@watson.ibm.com 4544 Pete Chown 4545 Skygate Technology Ltd 4546 pc@skygate.co.uk 4548 Taher Elgamal 4549 taher@securify.com 4550 Securify 4552 Pasi Eronen 4553 pasi.eronen@nokia.com 4554 Nokia 4556 Anil Gangolli 4557 anil@busybuddha.org 4559 Kipp Hickman 4561 Alfred Hoenes 4563 David Hopwood 4564 Independent Consultant 4565 EMail: david.hopwood@blueyonder.co.uk 4567 Phil Karlton (co-author of SSLv3) 4569 Paul Kocher (co-author of SSLv3) 4570 Cryptography Research 4571 paul@cryptography.com 4573 Hugo Krawczyk 4574 IBM 4575 hugo@ee.technion.ac.il 4577 Jan Mikkelsen 4578 Transactionware 4579 EMail: janm@transactionware.com 4581 Magnus Nystrom 4582 RSA Security 4583 EMail: magnus@rsasecurity.com 4585 Robert Relyea 4586 Netscape Communications 4587 relyea@netscape.com 4589 Jim Roskind 4590 Netscape Communications 4591 jar@netscape.com 4593 Michael Sabin 4595 Dan Simon 4596 Microsoft, Inc. 4597 dansimon@microsoft.com 4599 Tom Weinstein 4601 Tim Wright 4602 Vodafone 4603 EMail: timothy.wright@vodafone.com 4605 Comments 4607 The discussion list for the IETF TLS working group is located at the 4608 e-mail address . Information on the group and 4609 information on how to subscribe to the list is at 4610 4612 Archives of the list can be found at: 4613 4615 Full Copyright Statement 4617 Copyright (C) The IETF Trust (2008). 4619 This document is subject to the rights, licenses and restrictions 4620 contained in BCP 78, and except as set forth therein, the authors 4621 retain all their rights. 4623 This document and the information contained herein are provided on an 4624 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 4625 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 4626 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 4627 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 4628 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 4629 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4631 Intellectual Property 4633 The IETF takes no position regarding the validity or scope of any 4634 Intellectual Property Rights or other rights that might be claimed to 4635 pertain to the implementation or use of the technology described in 4636 this document or the extent to which any license under such rights 4637 might or might not be available; nor does it represent that it has 4638 made any independent effort to identify any such rights. Information 4639 on the procedures with respect to rights in RFC documents can be 4640 found in BCP 78 and BCP 79. 4642 Copies of IPR disclosures made to the IETF Secretariat and any 4643 assurances of licenses to be made available, or the result of an 4644 attempt made to obtain a general license or permission for the use of 4645 such proprietary rights by implementers or users of this 4646 specification can be obtained from the IETF on-line IPR repository at 4647 http://www.ietf.org/ipr. 4649 The IETF invites any interested party to bring to its attention any 4650 copyrights, patents or patent applications, or other proprietary 4651 rights that may cover technology that may be required to implement 4652 this standard. Please address the information to the IETF at 4653 ietf-ipr@ietf.org. 4655 Acknowledgment 4657 Funding for the RFC Editor function is provided by the IETF 4658 Administrative Support Activity (IASA).