idnits 2.17.1 draft-ietf-tls-protocol-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-23) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 2234: '...iant application MUST implement the ci...' Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 683 has weird spacing: '...gorithm bul...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 12, 1997) is 9659 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 253 -- Looks like a reference, but probably isn't: '1' on line 253 -- Looks like a reference, but probably isn't: '3' on line 3046 -- Looks like a reference, but probably isn't: '9' on line 289 -- Looks like a reference, but probably isn't: '2' on line 2377 -- Looks like a reference, but probably isn't: '4' on line 325 -- Looks like a reference, but probably isn't: '8' on line 326 -- Looks like a reference, but probably isn't: '10' on line 421 -- Looks like a reference, but probably isn't: '20' on line 2439 -- Looks like a reference, but probably isn't: '48' on line 2605 -- Looks like a reference, but probably isn't: '32' on line 2607 == Missing Reference: 'ChangeCipherSpec' is mentioned on line 1462, but not defined -- Looks like a reference, but probably isn't: '28' on line 2372 -- Looks like a reference, but probably isn't: '16' on line 2434 -- Looks like a reference, but probably isn't: '46' on line 2468 -- Looks like a reference, but probably isn't: '12' on line 2491 == Unused Reference: 'DH1' is defined on line 3431, but no explicit reference was found in the text == Unused Reference: 'FTP' is defined on line 3439, but no explicit reference was found in the text == Unused Reference: 'HTTP' is defined on line 3442, but no explicit reference was found in the text == Unused Reference: 'MD2' is defined on line 3452, but no explicit reference was found in the text == Unused Reference: 'TEL' is defined on line 3498, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. '3DES' -- Possible downref: Non-RFC (?) normative reference: ref. 'DES' -- Possible downref: Non-RFC (?) normative reference: ref. 'DH1' -- Possible downref: Non-RFC (?) normative reference: ref. 'DSS' -- Possible downref: Non-RFC (?) normative reference: ref. 'HTTP' ** Downref: Normative reference to an Informational RFC: RFC 2104 (ref. 'HMAC') -- Possible downref: Non-RFC (?) normative reference: ref. 'IDEA' ** Obsolete normative reference: RFC 1319 (ref. 'MD2') (Obsoleted by RFC 6149) ** Downref: Normative reference to an Informational RFC: RFC 1321 (ref. 'MD5') -- Possible downref: Non-RFC (?) normative reference: ref. 'PKCS1' -- Possible downref: Non-RFC (?) normative reference: ref. 'PKCS6' -- Possible downref: Non-RFC (?) normative reference: ref. 'PKCS7' -- Possible downref: Non-RFC (?) normative reference: ref. 'PKIX' -- Possible downref: Non-RFC (?) normative reference: ref. 'RC2' -- Possible downref: Non-RFC (?) normative reference: ref. 'RC4' -- Possible downref: Non-RFC (?) normative reference: ref. 'RSA' -- Possible downref: Non-RFC (?) normative reference: ref. 'RSADSI' -- Possible downref: Non-RFC (?) normative reference: ref. 'SHA' -- Possible downref: Non-RFC (?) normative reference: ref. 'SSL2' -- Possible downref: Non-RFC (?) normative reference: ref. 'SSL3' ** Obsolete normative reference: RFC 793 (ref. 'TCP') (Obsoleted by RFC 9293) -- Possible downref: Non-RFC (?) normative reference: ref. 'X509' ** Obsolete normative reference: RFC 1832 (ref. 'XDR') (Obsoleted by RFC 4506) Summary: 15 errors (**), 0 flaws (~~), 8 warnings (==), 36 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Transport Layer Security Working Group Tim Dierks 2 INTERNET-DRAFT Consensus Development 3 Expires May 12, 1998 Christopher Allen 4 Consensus Development 5 November 12, 1997 7 The TLS Protocol 8 Version 1.0 10 12 Status of this memo 14 This document is an Internet-Draft. Internet-Drafts are working 15 documents of the Internet Engineering Task Force (IETF), its areas, 16 and its working groups. Note that other groups may also distribute 17 working documents as Internet-Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six 20 months and may be updated, replaced, or made obsolete by other 21 documents at any time. It is inappropriate to use Internet-Drafts as 22 reference material or to cite them other than as work in progress. 24 To learn the current status of any Internet-Draft, please check the 25 1id-abstracts.txt listing contained in the Internet Drafts Shadow 26 Directories on ds.internic.net (US East Coast), nic.nordu.net 27 (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific 28 Rim). 30 Abstract 32 This document specifies Version 1.0 of the Transport Layer Security 33 (TLS) protocol. The TLS protocol provides communications privacy 34 over the Internet. The protocol allows client/server applications to 35 communicate in a way that is designed to prevent eavesdropping, 36 tampering, or message forgery. 38 Table of Contents 40 Status of this memo 1 41 Abstract 1 42 Table of Contents 2 43 1. Introduction 3 44 2. Goals 4 45 3. Goals of this document 5 46 4. Presentation language 5 47 4.1. Basic block size 6 48 4.2. Miscellaneous 6 49 4.3. Vectors 6 50 4.4. Numbers 7 51 4.5. Enumerateds 7 52 4.6. Constructed types 8 53 4.6.1. Variants 8 54 4.7. Cryptographic attributes 9 55 4.8. Constants 10 56 5. HMAC and the pseudorandom function 11 57 6. The TLS Record Protocol 12 58 6.1. Connection states 13 59 6.2. Record layer 15 60 6.2.1. Fragmentation 15 61 6.2.2. Record compression and decompression 16 62 6.2.3. Record payload protection 17 63 6.2.3.1. Null or standard stream cipher 18 64 6.2.3.2. CBC block cipher 18 65 6.3. Key calculation 19 66 6.3.1. Export key generation example 21 67 7. The TLS Handshake Protocol 21 68 7.1. Change cipher spec protocol 22 69 7.2. Alert protocol 23 70 7.2.1. Closure alerts 24 71 7.2.2. Error alerts 24 72 7.3. Handshake Protocol overview 27 73 7.4. Handshake protocol 29 74 7.4.1. Hello messages 30 75 7.4.1.1. Hello request 30 76 7.4.1.2. Client hello 31 77 7.4.1.3. Server hello 33 78 7.4.2. Server certificate 34 79 7.4.3. Server key exchange message 36 80 7.4.4. Certificate request 38 81 7.4.5. Server hello done 39 82 7.4.6. Client certificate 39 83 7.4.7. Client key exchange message 40 84 7.4.7.1. RSA encrypted premaster secret message 40 85 7.4.7.2. Client Diffie-Hellman public value 41 86 7.4.8. Certificate verify 42 87 7.4.9. Finished 42 88 8. Cryptographic computations 43 89 8.1. Computing the master secret 43 90 8.1.1. RSA 44 91 8.1.2. Diffie-Hellman 44 92 9. Mandatory Cipher Suites 44 93 10. Application data protocol 44 94 A. Protocol constant values 44 95 A.1. Record layer 44 96 A.2. Change cipher specs message 45 97 A.3. Alert messages 46 98 A.4. Handshake protocol 46 99 A.4.1. Hello messages 47 100 A.4.2. Server authentication and key exchange messages 47 101 A.4.3. Client authentication and key exchange messages 49 102 A.4.4. Handshake finalization message 49 103 A.5. The CipherSuite 49 104 A.6. The Security Parameters 51 105 B. Glossary 52 106 C. CipherSuite definitions 55 107 D. Implementation Notes 57 108 D.1. Temporary RSA keys 57 109 D.2. Random Number Generation and Seeding 58 110 D.3. Certificates and authentication 58 111 D.4. CipherSuites 58 112 E. Backward Compatibility With SSL 59 113 E.1. Version 2 client hello 60 114 E.2. Avoiding man-in-the-middle version rollback 61 115 F. Security analysis 61 116 F.1. Handshake protocol 62 117 F.1.1. Authentication and key exchange 62 118 F.1.1.1. Anonymous key exchange 62 119 F.1.1.2. RSA key exchange and authentication 63 120 F.1.1.3. Diffie-Hellman key exchange with authentication 63 121 F.1.2. Version rollback attacks 64 122 F.1.3. Detecting attacks against the handshake protocol 64 123 F.1.4. Resuming sessions 64 124 F.1.5. MD5 and SHA 65 125 F.2. Protecting application data 65 126 F.3. Final notes 66 127 G. Patent Statement 66 128 References 67 129 Credits 70 130 Comments 71 132 1. Introduction 134 The primary goal of the TLS Protocol is to provide privacy and data 135 integrity between two communicating applications. The protocol is 136 composed of two layers: the TLS Record Protocol and the TLS 137 Handshake Protocol. At the lowest level, layered on top of some 138 reliable transport protocol (e.g., TCP[TCP]), is the TLS Record 139 Protocol. The TLS Record Protocol provides connection security that 140 has two basic properties: 142 - The connection is private. Symmetric cryptography is used for 143 data encryption (e.g., DES[DES], RC4[RC4], etc.) The keys for 144 this symmetric encryption are generated uniquely for each 145 connection and are based on a secret negotiated by another 146 protocol (such as the TLS Handshake Protocol). The Record 147 Protocol can also be used without encryption. 149 - The connection is reliable. Message transport includes a message 150 integrity check using a keyed MAC. Secure hash functions (e.g., 151 SHA, MD5, etc.) are used for MAC computations. The Record 152 Protocol can operate without a MAC, but is generally only used 153 in this mode while another protocol is using the Record Protocol 154 as a transport for negotiating security parameters. 156 The TLS Record Protocol is used for encapsulation of various higher 157 level protocols. One such encapsulated protocol, the TLS Handshake 158 Protocol, allows the server and client to authenticate each other 159 and to negotiate an encryption algorithm and cryptographic keys 160 before the application protocol transmits or receives its first byte 161 of data. The TLS Handshake Protocol provides connection security 162 that has three basic properties: 164 - The peer's identity can be authenticated using asymmetric, or 165 public key, cryptography (e.g., RSA[RSA], DSS[DSS], etc.). This 166 authentication can be made optional, but is generally required 167 for at least one of the peers. 169 - The negotiation of a shared secret is secure: the negotiated 170 secret is unavailable to eavesdroppers, and for any 171 authenticated connection the secret cannot be obtained, even by 172 an attacker who can place himself in the middle of the 173 connection. 175 - The negotiation is reliable: no attacker can modify the 176 negotiation communication without being detected by the parties 177 to the communication. 179 One advantage of TLS is that it is application protocol independent. 180 Higher level protocols can layer on top of the TLS Protocol 181 transparently. The TLS standard, however, does not specify how 182 protocols add security with TLS; the decisions on how to initiate 183 TLS handshaking and how to interpret the authentication certificates 184 exchanged are left up to the judgment of the designers and 185 implementors of protocols which run on top of TLS. 187 2. Goals 189 The goals of TLS Protocol, in order of their priority, are: 191 1. Cryptographic security: TLS should be used to establish a secure 192 connection between two parties. 194 2. Interoperability: Independent programmers should be able to 195 develop applications utilizing TLS that will then be able to 196 successfully exchange cryptographic parameters without knowledge 197 of one another's code. 199 3. Extensibility: TLS seeks to provide a framework into which new 200 public key and bulk encryption methods can be incorporated as 201 necessary. This will also accomplish two sub-goals: to prevent 202 the need to create a new protocol (and risking the introduction 203 of possible new weaknesses) and to avoid the need to implement 204 an entire new security library. 206 4. Relative efficiency: Cryptographic operations tend to be highly 207 CPU intensive, particularly public key operations. For this 208 reason, the TLS protocol has incorporated an optional session 209 caching scheme to reduce the number of connections that need to 210 be established from scratch. Additionally, care has been taken 211 to reduce network activity. 213 3. Goals of this document 215 This document and the TLS protocol itself are based on the SSL 3.0 216 Protocol Specification as published by Netscape. The differences 217 between this protocol and SSL 3.0 are not dramatic, but they are 218 significant enough that TLS 1.0 and SSL 3.0 do not interoperate 219 (although TLS 1.0 does incorporate a mechanism by which a TLS 220 implementation can back down to SSL 3.0). This document is intended 221 primarily for readers who will be implementing the protocol and 222 those doing cryptographic analysis of it. The specification has been 223 written with this in mind, and it is intended to reflect the needs 224 of those two groups. For that reason, many of the 225 algorithm-dependent data structures and rules are included in the 226 body of the text (as opposed to in an appendix), providing easier 227 access to them. 229 This document is not intended to supply any details of service 230 definition nor interface definition, although it does cover select 231 areas of policy as they are required for the maintenance of solid 232 security. 234 4. Presentation language 236 This document deals with the formatting of data in an external 237 representation. The following very basic and somewhat casually 238 defined presentation syntax will be used. The syntax draws from 239 several sources in its structure. Although it resembles the 240 programming language "C" in its syntax and XDR [XDR] in both its 241 syntax and intent, it would be risky to draw too many parallels. The 242 purpose of this presentation language is to document TLS only, not 243 to have general application beyond that particular goal. 245 4.1. Basic block size 247 The representation of all data items is explicitly specified. The 248 basic data block size is one byte (i.e. 8 bits). Multiple byte data 249 items are concatenations of bytes, from left to right, from top to 250 bottom. From the bytestream a multi-byte item (a numeric in the 251 example) is formed (using C notation) by: 253 value = (byte[0] << 8*(n-1)) | (byte[1] << 8*(n-2)) | 254 ... | byte[n-1]; 256 This byte ordering for multi-byte values is the commonplace network 257 byte order or big endian format. 259 4.2. Miscellaneous 261 Comments begin with "/*" and end with "*/". 263 Optional components are denoted by enclosing them in "[[ ]]" double 264 brackets. 266 Single byte entities containing uninterpreted data are of type 267 opaque. 269 4.3. Vectors 271 A vector (single dimensioned array) is a stream of homogeneous data 272 elements. The size of the vector may be specified at documentation 273 time or left unspecified until runtime. In either case the length 274 declares the number of bytes, not the number of elements, in the 275 vector. The syntax for specifying a new type T' that is a fixed 276 length vector of type T is 278 T T'[n]; 280 Here T' occupies n bytes in the data stream, where n is a multiple 281 of the size of T. The length of the vector is not included in the 282 encoded stream. 284 In the following example, Datum is defined to be three consecutive 285 bytes that the protocol does not interpret, while Data is three 286 consecutive Datum, consuming a total of nine bytes. 288 opaque Datum[3]; /* three uninterpreted bytes */ 289 Datum Data[9]; /* 3 consecutive 3 byte vectors */ 291 Variable length vectors are defined by specifying a subrange of 292 legal lengths, inclusively, using the notation . 293 When encoded, the actual length precedes the vector's contents in 294 the byte stream. The length will be in the form of a number 295 consuming as many bytes as required to hold the vector's specified 296 maximum (ceiling) length. A variable length vector with an actual 297 length field of zero is referred to as an empty vector. 299 T T'; 301 In the following example, mandatory is a vector that must contain 302 between 300 and 400 bytes of type opaque. It can never be empty. The 303 actual length field consumes two bytes, a uint16, sufficient to 304 represent the value 400 (see Section 4.4). On the other hand, longer 305 can represent up to 800 bytes of data, or 400 uint16 elements, and 306 it may be empty. Its encoding will include a two byte actual length 307 field prepended to the vector. The length of an encoded vector must 308 be an even multiple of the length of a single element (for example, 309 a 17 byte vector of uint16 would be illegal). 311 opaque mandatory<300..400>; 312 /* length field is 2 bytes, cannot be empty */ 313 uint16 longer<0..800>; 314 /* zero to 400 16-bit unsigned integers */ 316 4.4. Numbers 318 The basic numeric data type is an unsigned byte (uint8). All larger 319 numeric data types are formed from fixed length series of bytes 320 concatenated as described in Section 4.1 and are also unsigned. The 321 following numeric types are predefined. 323 uint8 uint16[2]; 324 uint8 uint24[3]; 325 uint8 uint32[4]; 326 uint8 uint64[8]; 328 All values, here and elsewhere in the specification, are stored in 329 "network" or "big-endian" order; the uint32 represented by the hex 330 bytes 01 02 03 04 is equivalent to the decimal value 16909060. 332 4.5. Enumerateds 334 An additional sparse data type is available called enum. A field of 335 type enum can only assume the values declared in the definition. 336 Each definition is a different type. Only enumerateds of the same 337 type may be assigned or compared. Every element of an enumerated 338 must be assigned a value, as demonstrated in the following example. 339 Since the elements of the enumerated are not ordered, they can be 340 assigned any unique value, in any order. 342 enum { e1(v1), e2(v2), ... , en(vn) [[, (n)]] } Te; 344 Enumerateds occupy as much space in the byte stream as would its 345 maximal defined ordinal value. The following definition would cause 346 one byte to be used to carry fields of type Color. 348 enum { red(3), blue(5), white(7) } Color; 350 One may optionally specify a value without its associated tag to 351 force the width definition without defining a superfluous element. 352 In the following example, Taste will consume two bytes in the data 353 stream but can only assume the values 1, 2 or 4. 355 enum { sweet(1), sour(2), bitter(4), (32000) } Taste; 357 The names of the elements of an enumeration are scoped within the 358 defined type. In the first example, a fully qualified reference to 359 the second element of the enumeration would be Color.blue. Such 360 qualification is not required if the target of the assignment is 361 well specified. 363 Color color = Color.blue; /* overspecified, legal */ 364 Color color = blue; /* correct, type implicit */ 366 For enumerateds that are never converted to external representation, 367 the numerical information may be omitted. 369 enum { low, medium, high } Amount; 371 4.6. Constructed types 373 Structure types may be constructed from primitive types for 374 convenience. Each specification declares a new, unique type. The 375 syntax for definition is much like that of C. 377 struct { 378 T1 f1; 379 T2 f2; 380 ... 381 Tn fn; 382 } [[T]]; 384 The fields within a structure may be qualified using the type's name 385 using a syntax much like that available for enumerateds. For 386 example, T.f2 refers to the second field of the previous 387 declaration. Structure definitions may be embedded. 389 4.6.1. Variants 391 Defined structures may have variants based on some knowledge that is 392 available within the environment. The selector must be an enumerated 393 type that defines the possible variants the structure defines. There 394 must be a case arm for every element of the enumeration declared in 395 the select. The body of the variant structure may be given a label 396 for reference. The mechanism by which the variant is selected at 397 runtime is not prescribed by the presentation language. 399 struct { 400 T1 f1; 401 T2 f2; 402 .... 403 Tn fn; 404 select (E) { 405 case e1: Te1; 406 case e2: Te2; 407 .... 408 case en: Ten; 409 } [[fv]]; 410 } [[Tv]]; 412 For example: 414 enum { apple, orange } VariantTag; 415 struct { 416 uint16 number; 417 opaque string<0..10>; /* variable length */ 418 } V1; 419 struct { 420 uint32 number; 421 opaque string[10]; /* fixed length */ 422 } V2; 423 struct { 424 select (VariantTag) { /* value of selector is implicit */ 425 case apple: V1; /* VariantBody, tag = apple */ 426 case orange: V2; /* VariantBody, tag = orange */ 427 } variant_body; /* optional label on variant */ 428 } VariantRecord; 430 Variant structures may be qualified (narrowed) by specifying a value 431 for the selector prior to the type. For example, a 433 orange VariantRecord 435 is a narrowed type of a VariantRecord containing a variant_body of 436 type V2. 438 4.7. Cryptographic attributes 440 The four cryptographic operations digital signing, stream cipher 441 encryption, block cipher encryption, and public key encryption are 442 designated digitally-signed, stream-ciphered, block-ciphered, and 443 public-key-encrypted, respectively. A field's cryptographic 444 processing is specified by prepending an appropriate key word 445 designation before the field's type specification. Cryptographic 446 keys are implied by the current session state (see Section 5.1). 448 In digital signing, one-way hash functions are used as input for a 449 signing algorithm. In RSA signing, a 36-byte structure of two hashes 450 (one SHA and one MD5) is signed (encrypted with the private key). In 451 DSS, the 20 bytes of the SHA hash are run directly through the 452 Digital Signing Algorithm with no additional hashing. A 453 digitally-signed element is encoded as an opaque vector <0..2^16-1>, 454 where the length is specified by the signing algorithm and key. 456 In stream cipher encryption, the plaintext is exclusive-ORed with an 457 identical amount of output generated from a cryptographically-secure 458 keyed pseudorandom number generator. 460 In block cipher encryption, every block of plaintext encrypts to a 461 block of ciphertext. All block cipher encryption is done in CBC 462 (Cipher Block Chaining) mode, and all items which are block-ciphered 463 will be an exact multiple of the cipher block length. 465 In public key encryption, a public key algorithm is used to encrypt 466 data in such a way that it can be decrypted only with the matching 467 private key. A public-key-encrypted element is encoded as an opaque 468 vector <0..2^16-1>, where the length is specified by the signing 469 algorithm and key. 471 In the following example: 473 stream-ciphered struct { 474 uint8 field1; 475 uint8 field2; 476 digitally-signed opaque hash[20]; 477 } UserType; 479 The contents of hash are used as input for the signing algorithm, 480 then the entire structure is encrypted with a stream cipher. The 481 length of this structure, in bytes would be equal to 2 bytes for 482 field1 and field2, plus two bytes for the length of the signature, 483 plus the length of the output of the signing algorithm. This is 484 known due to the fact that the algorithm and key used for the 485 signing are known prior to encoding or decoding this structure. 487 4.8. Constants 489 Typed constants can be defined for purposes of specification by 490 declaring a symbol of the desired type and assigning values to it. 491 Under-specified types (opaque, variable length vectors, and 492 structures that contain opaque) cannot be assigned values. No fields 493 of a multi-element structure or vector may be elided. 495 For example, 497 struct { 498 uint8 f1; 499 uint8 f2; 500 } Example1; 501 Example1 ex1 = {1, 4}; /* assigns f1 = 1, f2 = 4 */ 503 5. HMAC and the pseudorandom function 505 A number of operations in the TLS record and handshake layer 506 required a keyed MAC; this is a secure digest of some data protected 507 by a secret. Forging the MAC is infeasible without knowledge of the 508 MAC secret. The construction we use for this operation is known as 509 HMAC, described in [HMAC]. 511 HMAC can be used with a variety of different hash algorithms. TLS 512 uses it in the handshake with two different algorithms: MD5 and 513 SHA-1, denoting these as HMAC_MD5(secret, data) and HMAC_SHA(secret, 514 data). Additional hash algorithms can be defined by cipher suites 515 and used to protect record data, but MD5 and SHA-1 are hard coded 516 into the description of the handshaking for this version of the 517 protocol. 519 In addition, a construction is required to do expansion of secrets 520 into blocks of data for the purposes of key generation or 521 validation. This pseudo-random function (PRF) takes as input a 522 secret, a seed, and an identifying label and produces an output of 523 arbitrary length. 525 In order to make the PRF as secure as possible, it uses two hash 526 algorithms in a way which should guarantee its security if either 527 algorithm remains secure. 529 First, we define a data expansion function, P_hash(secret, data) 530 which uses a single hash function to expand a secret and seed into 531 an arbitrary quantity of output: 533 P_hash(secret, seed) = HMAC_hash(secret, A(1) + seed) + 534 HMAC_hash(secret, A(2) + seed) + 535 HMAC_hash(secret, A(3) + seed) + ... 537 Where + indicates concatenation. 539 A() is defined as: 540 A(0) = seed 541 A(i) = HMAC_hash(secret, A(i-1)) 543 P_hash can be iterated as many times as is necessary to produce the 544 required quantity of data. For example, if P_SHA-1 was being used to 545 create 64 bytes of data, it would have to be iterated 4 times 546 (through A(4)), creating 80 bytes of output data; the last 16 bytes 547 of the final iteration would then be discarded, leaving 64 bytes of 548 output data. 550 TLS's PRF is created by splitting the secret into two halves and 551 using one half to generate data with P_MD5 and the other half to 552 generate data with P_SHA-1, then exclusive-or'ing the outputs of 553 these two expansion functions together. 555 S1 and S2 are the two halves of the secret and each is the same 556 length. S1 is taken from the first half of the secret, S2 from the 557 second half. Their length is created by rounding up the length of 558 the overall secret divided by two; thus, if the original secret is 559 an odd number of bytes long, the last byte of S1 will be the same as 560 the first byte of S2. 562 L_S = length in bytes of secret; 563 L_S1 = L_S2 = ceil(L_S / 2); 565 The secret is partitioned into two halves (with the possibility of 566 one shared byte) as described above, S1 taking the first L_S1 bytes 567 and S2 the last L_S2 bytes. 569 The PRF is then defined as the result of mixing the two pseudorandom 570 streams by exclusive-or'ing them together. 572 PRF(secret, label, seed) = P_MD5(S1, label + seed) XOR 573 P_SHA-1(S2, label + seed); 575 The label is an ASCII string. It should be included in the exact 576 form it is given without a length byte or trailing null character. 577 For example, the label "slithy toves" would be processed by hashing 578 the following bytes: 580 73 6C 69 74 68 79 20 74 6F 76 65 73 582 Note that because MD5 produces 16 byte outputs and SHA-1 produces 20 583 byte outputs, the boundaries of their internal iterations will not 584 be aligned; to generate a 80 byte output will involve P_MD5 being 585 iterated through A(5), while P_SHA-1 will only iterate through A(4). 587 6. The TLS Record Protocol 589 The TLS Record Protocol is a layered protocol. At each layer, 590 messages may include fields for length, description, and content. 591 The Record Protocol takes messages to be transmitted, fragments the 592 data into manageable blocks, optionally compresses the data, applies 593 a MAC, encrypts, and transmits the result. Received data is 594 decrypted, verified, decompressed, and reassembled, then delivered 595 to higher level clients. 597 Four record protocol clients are described in this document: the 598 handshake protocol, the alert protocol, the change cipher spec 599 protocol, and the application data protocol. In order to allow 600 extension of the TLS protocol, additional record types can be 601 supported by the record protocol. Any new record types should 602 allocate type values immediately beyond the ContentType values for 603 the four record types described here (see Appendix A.2). If a TLS 604 implementation receives a record type it does not understand, it 605 should just ignore it. Any protocol designed for use over TLS must 606 be carefully designed to deal with all possible attacks against it. 607 Note that because the type and length of a record are not protected 608 by encryption, care should be take to minimize the value of traffic 609 analysis of these values. 611 6.1. Connection states 613 A TLS connection state is the operating environment of the TLS 614 Record Protocol. It specifies a compression algorithm, encryption 615 algorithm, and MAC algorithm. In addition, the parameters for these 616 algorithms are known: the MAC secret and the bulk encryption keys 617 and IVs for the connection in both the read and the write 618 directions. Logically, there are always four connection states 619 outstanding: the current read and write states, and the pending read 620 and write states. All records are processed under the current read 621 and write states. The security parameters for the pending states can 622 be set by the TLS Handshake Protocol, and the Handshake Protocol can 623 selectively make either of the pending states current, in which case 624 the appropriate current state is disposed of and replaced with the 625 pending state; the pending state is then reinitialized to an empty 626 state. It is illegal to make a state which has not been initialized 627 with security parameters a current state. The initial current state 628 always specifies that no encryption, compression, or MAC will be 629 used. 631 The security parameters for a TLS Connection read and write state 632 are set by providing the following values: 634 connection end 635 Whether this entity is considered the "client" or the "server" 636 in this connection. 638 bulk encryption algorithm 639 An algorithm to be used for bulk encryption. This specification 640 includes the key size of this algorithm, how much of that key is 641 secret, whether it is a block or stream cipher, the block size 642 of the cipher (if appropriate), and whether it is considered an 643 "export" cipher. 645 MAC algorithm 646 An algorithm to be used for message authentication. This 647 specification includes the size of the hash which is returned by 648 the MAC algorithm. 650 compression algorithm 651 An algorithm to be used for data compression. This specification 652 must include all information the algorithm requires to do 653 compression. 655 master secret 656 A 48 byte secret shared between the two peers in the connection. 658 client random 659 A 32 byte value provided by the client. 661 server random 662 A 32 byte value provided by the server. 664 These parameters are defined in the presentation language as: 666 enum { server, client } ConnectionEnd; 668 enum { null, rc4, rc2, des, 3des, des40 } BulkCipherAlgorithm; 670 enum { stream, block } CipherType; 672 enum { true, false } IsExportable; 674 enum { null, md5, sha } MACAlgorithm; 676 enum { null(0), (255) } CompressionMethod; 678 /* The algorithms specified in CompressionMethod, 679 BulkCipherAlgorithm, and MACAlgorithm may be added to. */ 681 struct { 682 ConnectionEnd entity; 683 BulkCipherAlgorithm bulk_cipher_algorithm; 684 CipherType cipher_type; 685 uint8 key_size; 686 uint8 key_material_length; 687 IsExportable is_exportable; 688 MACAlgorithm mac_algorithm; 689 uint8 hash_size; 690 CompressionMethod compression_algorithm; 691 opaque master_secret[48]; 692 opaque client_random[32]; 693 opaque server_random[32]; 694 } SecurityParameters; 696 The record layer will use the security parameters to generate the 697 following six items: 699 client write MAC secret 700 server write MAC secret 701 client write key 702 server write key 703 client write IV (for block ciphers only) 704 server write IV (for block ciphers only) 706 The client write parameters are used by the server when receiving 707 and processing records and vice-versa. The algorithm used for 708 generating these items from the security parameters is described in 709 section 6.3. 711 Once the security parameters have been set and the keys have been 712 generated, the connection states can be instantiated by making them 713 the current states. These current states must be updated for each 714 record processed. Each connection state includes the following 715 elements: 717 compression state 718 The current state of the compression algorithm. 720 cipher state 721 The current state of the encryption algorithm. This will consist 722 of the scheduled key for that connection. In addition, for block 723 ciphers running in CBC mode (the only mode specified for TLS), 724 this will initially contain the IV for that connection state and 725 be updated to contain the ciphertext of the last block encrypted 726 or decrypted as records are processed. For stream ciphers, this 727 will contain whatever the necessary state information is to 728 allow the stream to continue to encrypt or decrypt data. 730 MAC secret 731 The MAC secret for this connection as generated above. 733 sequence number 734 Each connection state contains a sequence number, which is 735 maintained separately for read and write states. The sequence 736 number must be set to zero whenever a connection state is made 737 the active state. Sequence numbers are of type uint64 and may 738 not exceed 2^64-1. A sequence number is incremented after each 739 record: specifically, the first record which is transmitted 740 under a particular connection state should use sequence number 741 0. 743 6.2. Record layer 745 The TLS Record Layer receives uninterpreted data from higher layers 746 in non-empty blocks of arbitrary size. 748 6.2.1. Fragmentation 750 The record layer fragments information blocks into TLSPlaintext 751 records of 2^14 bytes or less. Client message boundaries are not 752 preserved in the record layer (i.e., multiple client messages of the 753 same ContentType may be coalesced into a single TLSPlaintext record, 754 or a single message may be fragmented across several records). 756 struct { 757 uint8 major, minor; 758 } ProtocolVersion; 760 enum { 761 change_cipher_spec(20), alert(21), handshake(22), 762 application_data(23), (255) 763 } ContentType; 765 struct { 766 ContentType type; 767 ProtocolVersion version; 768 uint16 length; 769 opaque fragment[TLSPlaintext.length]; 770 } TLSPlaintext; 772 type 773 The higher level protocol used to process the enclosed fragment. 775 version 776 The version of the protocol being employed. This document 777 describes TLS Version 1.0, which uses the version { 3, 1 }. The 778 version value 3.1 is historical: TLS version 1.0 is a minor 779 modification to the SSL 3.0 protocol, which bears the version 780 value 3.0. (See Appendix A.1). 782 length 783 The length (in bytes) of the following TLSPlaintext.fragment. 784 The length should not exceed 2^14. 786 fragment 787 The application data. This data is transparent and treated as an 788 independent block to be dealt with by the higher level protocol 789 specified by the type field. 791 Note: Data of different TLS Record layer content types may be 792 interleaved. Application data is generally of lower precedence 793 for transmission than other content types. 795 6.2.2. Record compression and decompression 797 All records are compressed using the compression algorithm defined 798 in the current session state. There is always an active compression 799 algorithm; however, initially it is defined as 800 CompressionMethod.null. The compression algorithm translates a 801 TLSPlaintext structure into a TLSCompressed structure. Compression 802 functions are initialized with default state information whenever a 803 connection state is made active. 805 Compression must be lossless and may not increase the content length 806 by more than 1024 bytes. If the decompression function encounters a 807 TLSCompressed.fragment that would decompress to a length in excess 808 of 2^14 bytes, it should report a fatal decompression failure error. 810 struct { 811 ContentType type; /* same as TLSPlaintext.type */ 812 ProtocolVersion version;/* same as TLSPlaintext.version */ 813 uint16 length; 814 opaque fragment[TLSCompressed.length]; 815 } TLSCompressed; 817 length 818 The length (in bytes) of the following TLSCompressed.fragment. 819 The length should not exceed 2^14 + 1024. 821 fragment 822 The compressed form of TLSPlaintext.fragment. 824 Note: A CompressionMethod.null operation is an identity operation; no 825 fields are altered. 827 Implementation note: 828 Decompression functions are responsible for ensuring that 829 messages cannot cause internal buffer overflows. 831 6.2.3. Record payload protection 833 The encryption and MAC functions translate a TLSCompressed structure 834 into a TLSCiphertext. The decryption functions reverse the process. 835 The MAC of the record also includes a sequence number so that 836 missing, extra or repeated messages are detectable. 838 struct { 839 ContentType type; 840 ProtocolVersion version; 841 uint16 length; 842 select (CipherSpec.cipher_type) { 843 case stream: GenericStreamCipher; 844 case block: GenericBlockCipher; 845 } fragment; 846 } TLSCiphertext; 848 type 849 The type field is identical to TLSCompressed.type. 851 version 852 The version field is identical to TLSCompressed.version. 854 length 855 The length (in bytes) of the following TLSCiphertext.fragment. 856 The length may not exceed 2^14 + 2048. 858 fragment 859 The encrypted form of TLSCompressed.fragment, with the MAC. 861 6.2.3.1. Null or standard stream cipher 863 Stream ciphers (including BulkCipherAlgorithm.null - see Appendix 864 A.6) convert TLSCompressed.fragment structures to and from stream 865 TLSCiphertext.fragment structures. 867 stream-ciphered struct { 868 opaque content[TLSCompressed.length]; 869 opaque MAC[CipherSpec.hash_size]; 870 } GenericStreamCipher; 872 The MAC is generated as: 874 HMAC_hash(MAC_write_secret, seq_num + TLSCompressed.type + 875 TLSCompressed.version + TLSCompressed.length + 876 TLSCompressed.fragment)); 878 where "+" denotes concatenation. 880 seq_num 881 The sequence number for this record. 883 hash 884 The hashing algorithm specified by 885 SecurityParameters.mac_algorithm. 887 Note that the MAC is computed before encryption. The stream cipher 888 encrypts the entire block, including the MAC. For stream ciphers 889 that do not use a synchronization vector (such as RC4), the stream 890 cipher state from the end of one record is simply used on the 891 subsequent packet. If the CipherSuite is TLS_NULL_WITH_NULL_NULL, 892 encryption consists of the identity operation (i.e., the data is not 893 encrypted and the MAC size is zero implying that no MAC is used). 894 TLSCiphertext.length is TLSCompressed.length plus 895 CipherSpec.hash_size. 897 6.2.3.2. CBC block cipher 899 For block ciphers (such as RC2 or DES), the encryption and MAC 900 functions convert TLSCompressed.fragment structures to and from 901 block TLSCiphertext.fragment structures. 903 block-ciphered struct { 904 opaque content[TLSCompressed.length]; 905 opaque MAC[CipherSpec.hash_size]; 906 uint8 padding[GenericBlockCipher.padding_length]; 907 uint8 padding_length; 908 } GenericBlockCipher; 910 The MAC is generated as described in Section 6.2.3.1. 912 padding 913 Padding that is added to force the length of the plaintext to be 914 an even multiple of the block cipher's block length. The padding 915 may be any length up to 255 bytes long, as long as it results in 916 the TLSCiphertext.length being an even multiple of the block 917 length. Lengths longer than necessary might be desirable to 918 frustrate attacks on a protocol based on analysis of the lengths 919 of exchanged messages. Each uint8 in the padding data vector 920 must be filled with the padding length value. 922 padding_length 923 The padding length should be such that the total size of the 924 GenericBlockCipher structure is a multiple of the cipher's block 925 length. Legal values range from zero to 255, inclusive. 927 The encrypted data length (TLSCiphertext.length) is one more than 928 the sum of TLSCompressed.length, CipherSpec.hash_size, and 929 padding_length. 931 Example: If the block length is 8 bytes, the content length 932 (TLSCompressed.length) is 61 bytes, and the MAC length is 20 933 bytes, the length before padding is 82 bytes. Thus, the 934 padding length modulo 8 must be equal to 6 in order to make 935 the total length an even multiple of 8 bytes (the block 936 length). The padding length can be 6, 14, 22, and so on, 937 through 254. If the padding length were the minimum necessary, 938 6, the padding would be 6 bytes, each containing the value 6. 940 Note: With block ciphers in CBC mode (Cipher Block Chaining) the 941 initialization vector (IV) for the first record is generated 942 with the other keys and secrets when the security parameters are 943 set. The IV for subsequent records is the last ciphertext block 944 from the previous record. 946 6.3. Key calculation 948 The Record Protocol requires an algorithm to generate keys, IVs, and 949 MAC secrets from the security parameters provided by the handshake 950 protocol. 952 The master secret is hashed into a sequence of secure bytes, which 953 are assigned to the MAC secrets, keys, and non-export IVs required 954 by the current connection state (see Appendix A.6). CipherSpecs 955 require a client write MAC secret, a server write MAC secret, a 956 client write key, a server write key, a client write IV, and a 957 server write IV, which are generated from the master secret in that 958 order. Unused values are empty. 960 When generating keys and MAC secrets, the master secret is used as 961 an entropy source, and the random values provide unencrypted salt 962 material and IVs for exportable ciphers. 964 To generate the key material, compute 966 key_block = PRF(SecurityParameters.master_secret, 967 "key expansion", 968 SecurityParameters.server_random + 969 SecurityParameters.client_random); 971 until enough output has been generated. Then the key_block is 972 partitioned as follows: 974 client_write_MAC_secret[SecurityParameters.hash_size] 975 server_write_MAC_secret[SecurityParameters.hash_size] 976 client_write_key[SecurityParameters.key_material] 977 server_write_key[SecurityParameters.key_material] 978 client_write_IV[SecurityParameters.IV_size] 979 server_write_IV[SecurityParameters.IV_size] 981 The client_write_IV and server_write_IV are only generated for 982 non-export block ciphers. For exportable block ciphers, the 983 initialization vectors are generated later, as described below. Any 984 extra key_block material is discarded. 986 Implementation note: 987 The cipher spec which is defined in this document which requires 988 the most material is 3DES_EDE_CBC_SHA: it requires 2 x 24 byte 989 keys, 2 x 20 byte MAC secrets, and 2 x 8 byte IVs, for a total 990 of 104 bytes of key material. 992 Exportable encryption algorithms (for which CipherSpec.is_exportable 993 is true) require additional processing as follows to derive their 994 final write keys: 996 final_client_write_key = 997 PRF(SecurityParameters.client_write_key, 998 "client write key", 999 SecurityParameters.client_random + 1000 SecurityParameters.server_random); 1001 final_server_write_key = 1002 PRF(SecurityParameters.server_write_key, 1003 "server write key", 1004 SecurityParameters.client_random + 1005 SecurityParameters.server_random); 1007 Exportable encryption algorithms derive their IVs solely from the 1008 random values from the hello messages: 1010 iv_block = PRF("", "IV block", SecurityParameters.client_random 1011 + 1012 SecurityParameters.server_random); 1014 The iv_block is partitioned into two initialization vectors as the 1015 key_block was above: 1017 client_write_IV[SecurityParameters.IV_size] 1018 server_write_IV[SecurityParameters.IV_size] 1020 Note that the PRF is used without a secret in this case: this just 1021 means that the secret has a length of zero bytes and contributes 1022 nothing to the hashing in the PRF. 1024 6.3.1. Export key generation example 1026 TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 requires five random bytes for 1027 each of the two encryption keys and 16 bytes for each of the MAC 1028 keys, for a total of 42 bytes of key material. The PRF output is 1029 stored in the key_block. The key_block is partitioned, and the write 1030 keys are salted because this is an exportable encryption algorithm. 1032 key_block = PRF(master_secret, 1033 "key expansion", 1034 master_secret + 1035 server_random + 1036 client_random)[0..41] 1037 client_write_MAC_secret = key_block[0..15] 1038 server_write_MAC_secret = key_block[16..31] 1039 client_write_key = key_block[32..36] 1040 server_write_key = key_block[37..41] 1041 final_client_write_key = PRF(client_write_key, 1042 "client write key", 1043 client_random + 1044 server_random)[0..15] 1045 final_server_write_key = PRF(server_write_key, 1046 "server write key", 1047 client_random + 1048 server_random)[0..15] 1049 iv_block = PRF("", "IV block", client_random + 1050 server_random)[0..15] 1051 client_write_IV = iv_block[0..7] 1052 server_write_IV = iv_block[8..15] 1054 7. The TLS Handshake Protocol 1056 The TLS Handshake Protocol consists of a suite of three 1057 sub-protocols which are used to allow peers to agree upon security 1058 parameters for the record layer, authenticate themselves, 1059 instantiate negotiated security parameters, and report error 1060 conditions to each other. 1062 The Handshake Protocol is responsible for negotiating a session, 1063 which consists of the following items: 1065 session identifier 1066 An arbitrary byte sequence chosen by the server to identify an 1067 active or resumable session state. 1069 peer certificate 1070 X509v3[X509] certificate of the peer. This element of the state 1071 may be null. 1073 compression method 1074 The algorithm used to compress data prior to encryption. 1076 cipher spec 1077 Specifies the bulk data encryption algorithm (such as null, DES, 1078 etc.) and a MAC algorithm (such as MD5 or SHA). It also defines 1079 cryptographic attributes such as the hash_size. (See Appendix 1080 A.6 for formal definition) 1082 master secret 1083 48-byte secret shared between the client and server. 1085 is resumable 1086 A flag indicating whether the session can be used to initiate 1087 new connections. 1089 These items are then used to create security parameters for use by 1090 the Record Layer when protecting application data. Many connections 1091 can be instantiated using the same session through the resumption 1092 feature of the TLS Handshake Protocol. 1094 7.1. Change cipher spec protocol 1096 The change cipher spec protocol exists to signal transitions in 1097 ciphering strategies. The protocol consists of a single message, 1098 which is encrypted and compressed under the current (not the 1099 pending) connection state. The message consists of a single byte of 1100 value 1. 1102 struct { 1103 enum { change_cipher_spec(1), (255) } type; 1104 } ChangeCipherSpec; 1106 The change cipher spec message is sent by both the client and server 1107 to notify the receiving party that subsequent records will be 1108 protected under the newly negotiated CipherSpec and keys. Reception 1109 of this message causes the receiver to instruct the Record Layer to 1110 immediately copy the read pending state into the read current state. 1111 Immediately after sending this message, the sender should instruct 1112 the record layer to make the write pending state the write active 1113 state. (See section 6.1.) The change cipher spec message is sent 1114 during the handshake after the security parameters have been agreed 1115 upon, but before the verifying finished message is sent (see section 1116 7.4.9). 1118 7.2. Alert protocol 1120 One of the content types supported by the TLS Record layer is the 1121 alert type. Alert messages convey the severity of the message and a 1122 description of the alert. Alert messages with a level of fatal 1123 result in the immediate termination of the connection. In this case, 1124 other connections corresponding to the session may continue, but the 1125 session identifier must be invalidated, preventing the failed 1126 session from being used to establish new connections. Like other 1127 messages, alert messages are encrypted and compressed, as specified 1128 by the current connection state. 1130 enum { warning(1), fatal(2), (255) } AlertLevel; 1132 enum { 1133 close_notify(0), 1134 unexpected_message(10), 1135 bad_record_mac(20), 1136 decryption_failed(21), 1137 record_overflow(22), 1138 decompression_failure(30), 1139 handshake_failure(40), 1140 bad_certificate(42), 1141 unsupported_certificate(43), 1142 certificate_revoked(44), 1143 certificate_expired(45), 1144 certificate_unknown(46), 1145 illegal_parameter(47), 1146 unknown_ca(48), 1147 access_denied(49), 1148 decode_error(50), 1149 decrypt_error(51), 1150 export_restriction(60), 1151 protocol_version(70), 1152 insufficient_security(71), 1153 internal_error(80), 1154 user_canceled(90), 1155 no_renegotiation(100), 1156 (255) 1157 } AlertDescription; 1159 struct { 1160 AlertLevel level; 1161 AlertDescription description; 1162 } Alert; 1164 7.2.1. Closure alerts 1166 The client and the server must share knowledge that the connection 1167 is ending in order to avoid a truncation attack. Either party may 1168 initiate the exchange of closing messages. 1170 close_notify 1171 This message notifies the recipient that the sender will not 1172 send any more messages on this connection. The session becomes 1173 unresumable if any connection is terminated without proper 1174 close_notify messages with level equal to warning. 1176 Either party may initiate a close by sending a close_notify alert. 1177 Any data received after a closure alert is ignored. 1179 Each party is required to send a close_notify alert before closing 1180 the write side of the connection. It is required that the other 1181 party respond with a close_notify alert of its own and close down 1182 the connection immediately, discarding any pending writes. It is not 1183 required for the initiator of the close to wait for the responding 1184 close_notify alert before closing the read side of the connection. 1186 NB: It is assumed that closing a connection reliably delivers 1187 pending data before destroying the transport. 1189 7.2.2. Error alerts 1191 Error handling in the TLS Handshake protocol is very simple. When an 1192 error is detected, the detecting party sends a message to the other 1193 party. Upon transmission or receipt of an fatal alert message, both 1194 parties immediately close the connection. Servers and clients are 1195 required to forget any session-identifiers, keys, and secrets 1196 associated with a failed connection. The following error alerts are 1197 defined: 1199 unexpected_message 1200 An inappropriate message was received. This alert is always 1201 fatal and should never be observed in communication between 1202 proper implementations. 1204 bad_record_mac 1205 This alert is returned if a record is received with an incorrect 1206 MAC. This message is always fatal. 1208 decryption_failed 1209 A TLSCiphertext decrypted in an invalid way: either it wasn`t an 1210 even multiple of the block length or its padding values, when 1211 checked, weren`t correct. This message is always fatal. 1213 record_overflow 1214 A TLSCiphertext record was received which had a length more than 1215 2^14+2048 bytes, or a record decrypted to a TLSCompressed record 1216 with more than 2^14+1024 bytes. This message is always fatal. 1218 decompression_failure 1219 The decompression function received improper input (e.g. data 1220 that would expand to excessive length). This message is always 1221 fatal. 1223 handshake_failure 1224 Reception of a handshake_failure alert message indicates that 1225 the sender was unable to negotiate an acceptable set of security 1226 parameters given the options available. This is a fatal error. 1228 bad_certificate 1229 A certificate was corrupt, contained signatures that did not 1230 verify correctly, etc. 1232 unsupported_certificate 1233 A certificate was of an unsupported type. 1235 certificate_revoked 1236 A certificate was revoked by its signer. 1238 certificate_expired 1239 A certificate has expired or is not currently valid. 1241 certificate_unknown 1242 Some other (unspecified) issue arose in processing the 1243 certificate, rendering it unacceptable. 1245 illegal_parameter 1246 A field in the handshake was out of range or inconsistent with 1247 other fields. This is always fatal. 1249 unknown_ca 1250 A valid certificate chain or partial chain was received, but the 1251 certificate was not accepted because the CA certificate could 1252 not be located or couldn`t be matched with a known, trusted CA. 1253 This message is always fatal. 1255 access_denied 1256 A valid certificate was received, but when access control was 1257 applied, the sender decided not to proceed with negotiation. 1258 This message is always fatal. 1260 decode_error 1261 A message could not be decoded because some field was out of the 1262 specified range or the length of the message was incorrect. This 1263 message is always fatal. 1265 decrypt_error 1266 A handshake cryptographic operation failed, including being 1267 unable to correctly verify a signature, decrypt a key exchange, 1268 or validate a finished message. 1270 export_restriction 1271 A negotiation not in compliance with export restrictions was 1272 detected; for example, attempting to transfer a 1024 bit 1273 ephemeral RSA key for the RSA_EXPORT handshake method. This 1274 message is always fatal. 1276 protocol_version 1277 The protocol version the client has attempted to negotiate is 1278 recognized, but not supported. (For example, old protocol 1279 versions might be avoided for security reasons). This message is 1280 always fatal. 1282 insufficient_security 1283 Returned instead of handshake_failure when a negotiation has 1284 failed specifically because the server requires ciphers more 1285 secure than those supported by the client. This message is 1286 always fatal. 1288 internal_error 1289 An internal error unrelated to the peer or the correctness of 1290 the protocol makes it impossible to continue (such as a memory 1291 allocation failure). This message is always fatal. 1293 user_canceled 1294 This handshake is being canceled for some reason unrelated to a 1295 protocol failure. If the user cancels an operation after the 1296 handshake is complete, just closing the connection by sending a 1297 close_notify is more appropriate. This alert should be followed 1298 by a close_notify. This message is generally a warning. 1300 no_renegotiation 1301 Sent by the client in response to a hello request or by the 1302 server in response to a client hello after initial handshaking. 1303 Either of these would normally lead to renegotiation; when that 1304 is not appropriate, the recipient should respond with this 1305 alert; at that point, the original requester can decide whether 1306 to proceed with the connection. One case where this would be 1307 appropriate would be where a server has spawned a process to 1308 satisfy a request; the process might receive security parameters 1309 (key length, authentication, etc.) at startup and it might be 1310 difficult to communicate changes to these parameters after that 1311 point. This message is always a warning. 1313 For all errors where an alert level is not explicitly specified, the 1314 sending party may determine at its discretion whether this is a 1315 fatal error or not; if an alert with a level of warning is received, 1316 the receiving party may decide at its discretion whether to treat 1317 this as a fatal error or not. However, all messages which are 1318 transmitted with a level of fatal must be treated as fatal messages. 1320 7.3. Handshake Protocol overview 1322 The cryptographic parameters of the session state are produced by 1323 the TLS Handshake Protocol, which operates on top of the TLS Record 1324 Layer. When a TLS client and server first start communicating, they 1325 agree on a protocol version, select cryptographic algorithms, 1326 optionally authenticate each other, and use public-key encryption 1327 techniques to generate shared secrets. 1329 The TLS Handshake Protocol involves the following steps: 1331 - Exchange hello messages to agree on algorithms, exchange random 1332 values, and check for session resumption. 1334 - Exchange the necessary cryptographic parameters to allow the 1335 client and server to agree on a premaster secret. 1337 - Exchange certificates and cryptographic information to allow the 1338 client and server to authenticate themselves. 1340 - Generate a master secret from the premaster secret and exchanged 1341 random values. 1343 - Provide security parameters to the record layer. 1345 - Allow the client and server to verify that their peer has 1346 calculated the same security parameters and that the handshake 1347 occurred without tampering by an attacker. 1349 Note that higher layers should not be overly reliant on TLS always 1350 negotiating the strongest possible connection between two peers: 1351 there are a number of ways a man in the middle attacker can attempt 1352 to make two entities drop down to the least secure method they 1353 support. The protocol has been designed to minimize this risk, but 1354 there are still attacks available: for example, an attacker could 1355 block access to the port a secure service runs on, or attempt to get 1356 the peers to negotiate an unauthenticated connection. The 1357 fundamental rule is that higher levels must be cognizant of what 1358 their security requirements are and never transmit information over 1359 a channel less secure than what they require. The TLS protocol is 1360 secure, in that any cipher suite offers its promised level of 1361 security: if you negotiate 3DES with a 1024 bit RSA key exchange 1362 with a host whose certificate you have verified, you can expect to 1363 be that secure. However, you should never send data over a link 1364 encrypted with 40 bit security unless you feel that data is worth no 1365 more than the effort required to break that encryption. 1367 These goals are achieved by the handshake protocol, which can be 1368 summarized as follows: The client sends a client hello message to 1369 which the server must respond with a server hello message, or else a 1370 fatal error will occur and the connection will fail. The client 1371 hello and server hello are used to establish security enhancement 1372 capabilities between client and server. The client hello and server 1373 hello establish the following attributes: Protocol Version, Session 1374 ID, Cipher Suite, and Compression Method. Additionally, two random 1375 values are generated and exchanged: ClientHello.random and 1376 ServerHello.random. 1378 The actual key exchange uses up to four messages: the server 1379 certificate, the server key exchange, the client certificate, and 1380 the client key exchange. New key exchange methods can be created by 1381 specifying a format for these messages and defining the use of the 1382 messages to allow the client and server to agree upon a shared 1383 secret. This secret should be quite long; currently defined key 1384 exchange methods exchange secrets which range from 48 to 128 bytes 1385 in length. 1387 Following the hello messages, the server will send its certificate, 1388 if it is to be authenticated. Additionally, a server key exchange 1389 message may be sent, if it is required (e.g. if their server has no 1390 certificate, or if its certificate is for signing only). If the 1391 server is authenticated, it may request a certificate from the 1392 client, if that is appropriate to the cipher suite selected. Now the 1393 server will send the server hello done message, indicating that the 1394 hello-message phase of the handshake is complete. The server will 1395 then wait for a client response. If the server has sent a 1396 certificate request message, the client must send the certificate 1397 message. The client key exchange message is now sent, and the 1398 content of that message will depend on the public key algorithm 1399 selected between the client hello and the server hello. If the 1400 client has sent a certificate with signing ability, a 1401 digitally-signed certificate verify message is sent to explicitly 1402 verify the certificate. 1404 At this point, a change cipher spec message is sent by the client, 1405 and the client copies the pending Cipher Spec into the current 1406 Cipher Spec. The client then immediately sends the finished message 1407 under the new algorithms, keys, and secrets. In response, the server 1408 will send its own change cipher spec message, transfer the pending 1409 to the current Cipher Spec, and send its finished message under the 1410 new Cipher Spec. At this point, the handshake is complete and the 1411 client and server may begin to exchange application layer data. (See 1412 flow chart below.) 1414 Client Server 1416 ClientHello --------> 1417 ServerHello 1418 Certificate* 1419 ServerKeyExchange* 1420 CertificateRequest* 1421 <-------- ServerHelloDone 1422 Certificate* 1423 ClientKeyExchange 1424 CertificateVerify* 1425 [ChangeCipherSpec] 1426 Finished --------> 1427 [ChangeCipherSpec] 1428 <-------- Finished 1429 Application Data <-------> Application Data 1431 Fig. 1 - Message flow for a full handshake 1433 * Indicates optional or situation-dependent messages that are not 1434 always sent. 1436 Note: To help avoid pipeline stalls, ChangeCipherSpec is an 1437 independent TLS Protocol content type, and is not actually a TLS 1438 handshake message. 1440 When the client and server decide to resume a previous session or 1441 duplicate an existing session (instead of negotiating new security 1442 parameters) the message flow is as follows: 1444 The client sends a ClientHello using the Session ID of the session 1445 to be resumed. The server then checks its session cache for a match. 1446 If a match is found, and the server is willing to re-establish the 1447 connection under the specified session state, it will send a 1448 ServerHello with the same Session ID value. At this point, both 1449 client and server must send change cipher spec messages and proceed 1450 directly to finished messages. Once the re-establishment is 1451 complete, the client and server may begin to exchange application 1452 layer data. (See flow chart below.) If a Session ID match is not 1453 found, the server generates a new session ID and the TLS client and 1454 server perform a full handshake. 1456 Client Server 1458 ClientHello --------> 1459 ServerHello 1460 [ChangeCipherSpec] 1461 <-------- Finished 1462 [ChangeCipherSpec] 1463 Finished --------> 1464 Application Data <-------> Application Data 1466 Fig. 2 - Message flow for an abbreviated handshake 1468 The contents and significance of each message will be presented in 1469 detail in the following sections. 1471 7.4. Handshake protocol 1473 The TLS Handshake Protocol is one of the defined higher level 1474 clients of the TLS Record Protocol. This protocol is used to 1475 negotiate the secure attributes of a session. Handshake messages are 1476 supplied to the TLS Record Layer, where they are encapsulated within 1477 one or more TLSPlaintext structures, which are processed and 1478 transmitted as specified by the current active session state. 1480 enum { 1481 hello_request(0), client_hello(1), server_hello(2), 1482 certificate(11), server_key_exchange (12), 1483 certificate_request(13), server_hello_done(14), 1484 certificate_verify(15), client_key_exchange(16), 1485 finished(20), (255) 1486 } HandshakeType; 1488 struct { 1489 HandshakeType msg_type; /* handshake type */ 1490 uint24 length; /* bytes in message */ 1491 select (HandshakeType) { 1492 case hello_request: HelloRequest; 1493 case client_hello: ClientHello; 1494 case server_hello: ServerHello; 1495 case certificate: Certificate; 1496 case server_key_exchange: ServerKeyExchange; 1497 case certificate_request: CertificateRequest; 1498 case server_hello_done: ServerHelloDone; 1499 case certificate_verify: CertificateVerify; 1500 case client_key_exchange: ClientKeyExchange; 1501 case finished: Finished; 1502 } body; 1503 } Handshake; 1505 The handshake protocol messages are presented below in the order 1506 they must be sent; sending handshake messages in an unexpected order 1507 results in a fatal error. Unneeded handshake messages can be 1508 omitted, however. Note one exception to the ordering: the 1509 Certificate message is used twice in the handshake (from server to 1510 client, then from client to server), but described only in its first 1511 position. The one message which is not bound by these ordering rules 1512 in the Hello Request message, which can be sent at any time, but 1513 which should be ignored by the client if it arrives in the middle of 1514 a handshake. 1516 7.4.1. Hello messages 1518 The hello phase messages are used to exchange security enhancement 1519 capabilities between the client and server. When a new session 1520 begins, the Record Layer's connection state encryption, hash, and 1521 compression algorithms are initialized to null. The current 1522 connection state is used for renegotiation messages. 1524 7.4.1.1. Hello request 1526 When this message will be sent: 1527 The hello request message may be sent by the server at any time. 1529 Meaning of this message: 1530 Hello request is a simple notification that the client should 1531 begin the negotiation process anew by sending a client hello 1532 message when convenient. This message will be ignored by the 1533 client if the client is currently negotiating a session. This 1534 message may be ignored by the client if it does not wish to 1535 renegotiate a session, or the client may, if it wishes, respond 1536 with a no_renegotiation alert. Since handshake messages are 1537 intended to have transmission precedence over application data, 1538 it is expected that the negotiation will begin before no more 1539 than a few records are received from the client. If the server 1540 sends a hello request but does not receive a client hello in 1541 response, it may close the connection with a fatal alert. 1543 After sending a hello request, servers should not repeat the request 1544 until the subsequent handshake negotiation is complete. 1546 Structure of this message: 1547 struct { } HelloRequest; 1549 Note: This message should never be included in the message hashes 1550 which are maintained throughout the handshake and used in the 1551 finished messages and the certificate verify message. 1553 7.4.1.2. Client hello 1555 When this message will be sent: 1556 When a client first connects to a server it is required to send 1557 the client hello as its first message. The client can also send 1558 a client hello in response to a hello request or on its own 1559 initiative in order to renegotiate the security parameters in an 1560 existing connection. 1562 Structure of this message: 1563 The client hello message includes a random structure, which is 1564 used later in the protocol. 1566 struct { 1567 uint32 gmt_unix_time; 1568 opaque random_bytes[28]; 1569 } Random; 1571 gmt_unix_time 1572 The current time and date in standard UNIX 32-bit format 1573 (seconds since the midnight starting Jan 1, 1970, GMT) according 1574 to the sender's internal clock. Clocks are not required to be 1575 set correctly by the basic TLS Protocol; higher level or 1576 application protocols may define additional requirements. 1578 random_bytes 1579 28 bytes generated by a secure random number generator. 1581 The client hello message includes a variable length session 1582 identifier. If not empty, the value identifies a session between the 1583 same client and server whose security parameters the client wishes 1584 to reuse. The session identifier may be from an earlier connection, 1585 this connection, or another currently active connection. The second 1586 option is useful if the client only wishes to update the random 1587 structures and derived values of a connection, while the third 1588 option makes it possible to establish several independent secure 1589 connections without repeating the full handshake protocol. These 1590 independent connections may occur sequentially or simultaneously; a 1591 SessionID becomes valid when the handshake negotiating it completes 1592 with the exchange of Finished messages and persists until removed 1593 due to aging or because a fatal error was encountered on a 1594 connection associated with the session. The actual contents of the 1595 SessionID are defined by the server. 1597 opaque SessionID<0..32>; 1599 Warning: 1600 Because the SessionID is transmitted without encryption or 1601 immediate MAC protection, servers must not place confidential 1602 information in session identifiers or let the contents of fake 1603 session identifiers cause any breach of security. (Note that the 1604 content of the handshake as a whole, including the SessionID, is 1605 protected by the Finished messages exchanged at the end of the 1606 handshake.) 1608 The CipherSuite list, passed from the client to the server in the 1609 client hello message, contains the combinations of cryptographic 1610 algorithms supported by the client in order of the client's 1611 preference (favorite choice first). Each CipherSuite defines a key 1612 exchange algorithm, a bulk encryption algorithm (including secret 1613 key length) and a MAC algorithm. The server will select a cipher 1614 suite or, if no acceptable choices are presented, return a handshake 1615 failure alert and close the connection. 1617 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 1619 The client hello includes a list of compression algorithms supported 1620 by the client, ordered according to the client's preference. 1622 enum { null(0), (255) } CompressionMethod; 1624 struct { 1625 ProtocolVersion client_version; 1626 Random random; 1627 SessionID session_id; 1628 CipherSuite cipher_suites<2..2^16-1>; 1629 CompressionMethod compression_methods<1..2^8-1>; 1630 } ClientHello; 1632 client_version 1633 The version of the TLS protocol by which the client wishes to 1634 communicate during this session. This should be the latest 1635 (highest valued) version supported by the client. For this 1636 version of the specification, the version will be 3.1 (See 1637 Appendix E for details about backward compatibility). 1639 random 1640 A client-generated random structure. 1642 session_id 1643 The ID of a session the client wishes to use for this 1644 connection. This field should be empty if no session_id is 1645 available or the client wishes to generate new security 1646 parameters. 1648 cipher_suites 1649 This is a list of the cryptographic options supported by the 1650 client, with the client's first preference first. If the 1651 session_id field is not empty (implying a session resumption 1652 request) this vector must include at least the cipher_suite from 1653 that session. Values are defined in Appendix A.5. 1655 compression_methods 1656 This is a list of the compression methods supported by the 1657 client, sorted by client preference. If the session_id field is 1658 not empty (implying a session resumption request) it must 1659 include the compression_method from that session. This vector 1660 must contain, and all implementations must support, 1661 CompressionMethod.null. Thus, a client and server will always be 1662 able to agree on a compression method. 1664 After sending the client hello message, the client waits for a 1665 server hello message. Any other handshake message returned by the 1666 server except for a hello request is treated as a fatal error. 1668 Forward compatibility note: 1669 In the interests of forward compatibility, it is permitted for a 1670 client hello message to include extra data after the compression 1671 methods. This data must be included in the handshake hashes, but 1672 must otherwise be ignored. This is the only handshake message 1673 for which this is legal; for all other messages, the amount of 1674 data in the message must match the description of the message 1675 precisely. 1677 7.4.1.3. Server hello 1679 When this message will be sent: 1680 The server will send this message in response to a client hello 1681 message when it was able to find an acceptable set of 1682 algorithms. If it cannot find such a match, it will respond with 1683 a handshake failure alert. 1685 Structure of this message: 1686 struct { 1687 ProtocolVersion server_version; 1688 Random random; 1689 SessionID session_id; 1690 CipherSuite cipher_suite; 1691 CompressionMethod compression_method; 1692 } ServerHello; 1694 server_version 1695 This field will contain the lower of that suggested by the 1696 client in the client hello and the highest supported by the 1697 server. For this version of the specification, the version is 1698 3.1 (See Appendix E for details about backward compatibility). 1700 random 1701 This structure is generated by the server and must be different 1702 from (and independent of) ClientHello.random. 1704 session_id 1705 This is the identity of the session corresponding to this 1706 connection. If the ClientHello.session_id was non-empty, the 1707 server will look in its session cache for a match. If a match is 1708 found and the server is willing to establish the new connection 1709 using the specified session state, the server will respond with 1710 the same value as was supplied by the client. This indicates a 1711 resumed session and dictates that the parties must proceed 1712 directly to the finished messages. Otherwise this field will 1713 contain a different value identifying the new session. The 1714 server may return an empty session_id to indicate that the 1715 session will not be cached and therefore cannot be resumed. If a 1716 session is resumed, it must be resumed using the same cipher 1717 suite it was originally negotiated with. 1719 cipher_suite 1720 The single cipher suite selected by the server from the list in 1721 ClientHello.cipher_suites. For resumed sessions this field is 1722 the value from the state of the session being resumed. 1724 compression_method 1725 The single compression algorithm selected by the server from the 1726 list in ClientHello.compression_methods. For resumed sessions 1727 this field is the value from the resumed session state. 1729 7.4.2. Server certificate 1731 When this message will be sent: 1732 The server must send a certificate whenever the agreed-upon key 1733 exchange method is not an anonymous one. This message will 1734 always immediately follow the server hello message. 1736 Meaning of this message: 1737 The certificate type must be appropriate for the selected cipher 1738 suite's key exchange algorithm, and is generally an X.509v3 1739 certificate. It must contain a key which matches the key 1740 exchange method, as follows. Unless otherwise specified, the 1741 signing algorithm for the certificate must be the same as the 1742 algorithm for the certificate key. Unless otherwise specified, 1743 the public key may be of any length. 1745 Key Exchange Algorithm Certificate Key Type 1747 RSA RSA public key; the certificate must 1748 allow the key to be used for encryption. 1750 RSA_EXPORT RSA public key of length greater than 1751 512 bits which can be used for signing, 1752 or a key of 512 bits or shorter which 1753 can be used for either encryption or 1754 signing. 1756 DHE_DSS DSS public key. 1758 DHE_DSS_EXPORT DSS public key. 1760 DHE_RSA RSA public key which can be used for 1761 signing. 1763 DHE_RSA_EXPORT RSA public key which can be used for 1764 signing. 1766 DH_DSS Diffie-Hellman key. The algorithm used 1767 to sign the certificate should be DSS. 1769 DH_RSA Diffie-Hellman key. The algorithm used 1770 to sign the certificate should be RSA. 1772 All certificate profiles, key and cryptographic formats are defined 1773 by the IETF PKIX working group [PKIX]. When a key usage extension is 1774 present, the digitalSignature bit must be set for the key to be 1775 eligible for signing, as described above, and the keyEncipherment 1776 bit must be present to allow encryption, as described above. The 1777 keyAgreement bit must be set on Diffie-Hellman certificates. 1779 As CipherSuites which specify new key exchange methods are specified 1780 for the TLS Protocol, they will imply certificate format and the 1781 required encoded keying information. 1783 Structure of this message: 1784 opaque ASN.1Cert<1..2^24-1>; 1785 struct { 1786 ASN.1Cert certificate_list<0..2^24-1>; 1787 } Certificate; 1789 certificate_list 1790 This is a sequence (chain) of X.509v3 certificates. The sender's 1791 certificate must come first in the list. Each following 1792 certificate must directly certify the one preceding it. Because 1793 certificate validation requires that root keys be distributed 1794 independently, the self-signed certificate which specifies the 1795 root certificate authority may optionally be omitted from the 1796 chain, under the assumption that the remote end must already 1797 possess it in order to validate it in any case. 1799 The same message type and structure will be used for the client's 1800 response to a certificate request message. Note that a client may 1801 send no certificates if it does not have an appropriate certificate 1802 to send in response to the server's authentication request. 1804 Note: PKCS #7 [PKCS7] is not used as the format for the certificate 1805 vector because PKCS #6 [PKCS6] extended certificates are not 1806 used. Also PKCS #7 defines a SET rather than a SEQUENCE, making 1807 the task of parsing the list more difficult. 1809 7.4.3. Server key exchange message 1811 When this message will be sent: 1812 This message will be sent immediately after the server 1813 certificate message (or the server hello message, if this is an 1814 anonymous negotiation). 1816 The server key exchange message is sent by the server only when 1817 the server certificate message (if sent) does not contain enough 1818 data to allow the client to exchange a premaster secret. This is 1819 true for the following key exchange methods: 1821 RSA_EXPORT (if the public key in the server certificate is 1822 longer than 512 bits) 1823 DHE_DSS 1824 DHE_DSS_EXPORT 1825 DHE_RSA 1826 DHE_RSA_EXPORT 1827 DH_anon 1829 It is not legal to send the server key exchange message for the 1830 following key exchange methods: 1832 RSA 1833 RSA_EXPORT (when the public key in the server certificate is 1834 less than or equal to 512 bits in length) 1835 DH_DSS 1836 DH_RSA 1838 Meaning of this message: 1839 This message conveys cryptographic information to allow the 1840 client to communicate the premaster secret: either an RSA public 1841 key to encrypt the premaster secret with, or a Diffie-Hellman 1842 public key with which the client can complete a key exchange 1843 (with the result being the premaster secret.) 1845 As additional CipherSuites are defined for TLS which include new key 1846 exchange algorithms, the server key exchange message will be sent if 1847 and only if the certificate type associated with the key exchange 1848 algorithm does not provide enough information for the client to 1849 exchange a premaster secret. 1851 Note: According to current US export law, RSA moduli larger than 512 1852 bits may not be used for key exchange in software exported from 1853 the US. With this message, the larger RSA keys encoded in 1854 certificates may be used to sign temporary shorter RSA keys for 1855 the RSA_EXPORT key exchange method. 1857 Structure of this message: 1858 enum { rsa, diffie_hellman } KeyExchangeAlgorithm; 1860 struct { 1861 opaque rsa_modulus<1..2^16-1>; 1862 opaque rsa_exponent<1..2^16-1>; 1863 } ServerRSAParams; 1865 rsa_modulus 1866 The modulus of the server's temporary RSA key. 1868 rsa_exponent 1869 The public exponent of the server's temporary RSA key. 1871 struct { 1872 opaque dh_p<1..2^16-1>; 1873 opaque dh_g<1..2^16-1>; 1874 opaque dh_Ys<1..2^16-1>; 1875 } ServerDHParams; /* Ephemeral DH parameters */ 1877 dh_p 1878 The prime modulus used for the Diffie-Hellman operation. 1880 dh_g 1881 The generator used for the Diffie-Hellman operation. 1883 dh_Ys 1884 The server's Diffie-Hellman public value (g^X mod p). 1886 struct { 1887 select (KeyExchangeAlgorithm) { 1888 case diffie_hellman: 1889 ServerDHParams params; 1890 Signature signed_params; 1891 case rsa: 1892 ServerRSAParams params; 1893 Signature signed_params; 1894 }; 1895 } ServerKeyExchange; 1897 params 1898 The server's key exchange parameters. 1900 signed_params 1901 For non-anonymous key exchanges, a hash of the corresponding 1902 params value, with the signature appropriate to that hash 1903 applied. 1905 md5_hash 1906 MD5(ClientHello.random + ServerHello.random + ServerParams); 1908 sha_hash 1909 SHA(ClientHello.random + ServerHello.random + ServerParams); 1911 enum { anonymous, rsa, dsa } SignatureAlgorithm; 1913 select (SignatureAlgorithm) 1914 { case anonymous: struct { }; 1915 case rsa: 1916 digitally-signed struct { 1917 opaque md5_hash[16]; 1918 opaque sha_hash[20]; 1919 }; 1920 case dsa: 1921 digitally-signed struct { 1922 opaque sha_hash[20]; 1923 }; 1924 } Signature; 1926 7.4.4. Certificate request 1928 When this message will be sent: 1929 A non-anonymous server can optionally request a certificate from 1930 the client, if appropriate for the selected cipher suite. This 1931 message, if sent, will immediately follow the Server Key 1932 Exchange message (if it is sent; otherwise, the Server 1933 Certificate message). 1935 Structure of this message: 1936 enum { 1937 rsa_sign(1), dss_sign(2), rsa_fixed_dh(3), dss_fixed_dh(4), 1938 (255) 1939 } ClientCertificateType; 1940 opaque DistinguishedName<1..2^16-1>; 1942 struct { 1943 ClientCertificateType certificate_types<1..2^8-1>; 1944 DistinguishedName certificate_authorities<3..2^16-1>; 1945 } CertificateRequest; 1947 certificate_types 1948 This field is a list of the types of certificates requested, 1949 sorted in order of the server's preference. 1951 certificate_authorities 1952 A list of the distinguished names of acceptable certificate 1953 authorities. These distinguished names may specify a desired 1954 distinguished name for a root CA or for a subordinate CA; 1955 thus, this message can be used both to describe known roots 1956 and a desired authorization space. 1958 Note: DistinguishedName is derived from [X509]. 1960 Note: It is a fatal handshake_failure alert for an anonymous server to 1961 request client identification. 1963 7.4.5. Server hello done 1965 When this message will be sent: 1966 The server hello done message is sent by the server to indicate 1967 the end of the server hello and associated messages. After 1968 sending this message the server will wait for a client response. 1970 Meaning of this message: 1971 This message means that the server is done sending messages to 1972 support the key exchange, and the client can proceed with its 1973 phase of the key exchange. 1975 Upon receipt of the server hello done message the client should 1976 verify that the server provided a valid certificate if required 1977 and check that the server hello parameters are acceptable. 1979 Structure of this message: 1980 struct { } ServerHelloDone; 1982 7.4.6. Client certificate 1984 When this message will be sent: 1985 This is the first message the client can send after receiving a 1986 server hello done message. This message is only sent if the 1987 server requests a certificate. If no suitable certificate is 1988 available, the client should send a certificate message 1989 containing no certificates. If client authentication is required 1990 by the server for the handshake to continue, it may respond with 1991 a fatal handshake failure alert. Client certificates are sent 1992 using the Certificate structure defined in Section 7.4.2. 1994 Note: When using a static Diffie-Hellman based key exchange method 1995 (DH_DSS or DH_RSA), if client authentication is requested, the 1996 Diffie-Hellman group and generator encoded in the client's 1997 certificate must match the server specified Diffie-Hellman 1998 parameters if the client's parameters are to be used for the key 1999 exchange. 2001 7.4.7. Client key exchange message 2003 When this message will be sent: 2004 This message is always sent by the client. It will immediately 2005 follow the client certificate message, if it is sent. Otherwise 2006 it will be the first message sent by the client after it 2007 receives the server hello done message. 2009 Meaning of this message: 2010 With this message, the premaster secret is set, either though 2011 direct transmission of the RSA-encrypted secret, or by the 2012 transmission of Diffie-Hellman parameters which will allow each 2013 side to agree upon the same premaster secret. When the key 2014 exchange method is DH_RSA or DH_DSS, client certification has 2015 been requested, and the client was able to respond with a 2016 certificate which contained a Diffie-Hellman public key whose 2017 parameters (group and generator) matched those specified by the 2018 server in its certificate, this message will not contain any 2019 data. 2021 Structure of this message: 2022 The choice of messages depends on which key exchange method has 2023 been selected. See Section 7.4.3 for the KeyExchangeAlgorithm 2024 definition. 2026 struct { 2027 select (KeyExchangeAlgorithm) { 2028 case rsa: EncryptedPreMasterSecret; 2029 case diffie_hellman: ClientDiffieHellmanPublic; 2030 } exchange_keys; 2031 } ClientKeyExchange; 2033 7.4.7.1. RSA encrypted premaster secret message 2035 Meaning of this message: 2036 If RSA is being used for key agreement and authentication, the 2037 client generates a 48-byte premaster secret, encrypts it using 2038 the public key from the server's certificate or the temporary 2039 RSA key provided in a server key exchange message, and sends the 2040 result in an encrypted premaster secret message. This structure 2041 is a variant of the client key exchange message, not a message 2042 in itself. 2044 Structure of this message: 2045 struct { 2046 ProtocolVersion client_version; 2047 opaque random[46]; 2048 } PreMasterSecret; 2050 client_version 2051 The latest (newest) version supported by the client. This is 2052 used to detect version roll-back attacks. Upon receiving the 2053 premaster secret, the server should check that this value 2054 matches the value transmitted by the client in the client 2055 hello message. 2057 random 2058 46 securely-generated random bytes. 2060 struct { 2061 public-key-encrypted PreMasterSecret pre_master_secret; 2062 } EncryptedPreMasterSecret; 2064 pre_master_secret 2065 This random value is generated by the client and is used to 2066 generate the master secret, as specified in Section 8.1. 2068 7.4.7.2. Client Diffie-Hellman public value 2070 Meaning of this message: 2071 This structure conveys the client's Diffie-Hellman public value 2072 (Yc) if it was not already included in the client's certificate. 2073 The encoding used for Yc is determined by the enumerated 2074 PublicValueEncoding. This structure is a variant of the client 2075 key exchange message, not a message in itself. 2077 Structure of this message: 2078 enum { implicit, explicit } PublicValueEncoding; 2080 implicit 2081 If the client certificate already contains a suitable 2082 Diffie-Hellman key, then Yc is implicit and does not need to 2083 be sent again. In this case, the Client Key Exchange message 2084 will be sent, but will be empty. 2086 explicit 2087 Yc needs to be sent. 2089 struct { 2090 select (PublicValueEncoding) { 2091 case implicit: struct { }; 2092 case explicit: opaque dh_Yc<1..2^16-1>; 2093 } dh_public; 2094 } ClientDiffieHellmanPublic; 2095 dh_Yc 2096 The client's Diffie-Hellman public value (Yc). 2098 7.4.8. Certificate verify 2100 When this message will be sent: 2101 This message is used to provide explicit verification of a 2102 client certificate. This message is only sent following a client 2103 certificate that has signing capability (i.e. all certificates 2104 except those containing fixed Diffie-Hellman parameters). When 2105 sent, it will immediately follow the client key exchange 2106 message. 2108 Structure of this message: 2109 struct { 2110 Signature signature; 2111 } CertificateVerify; 2113 The Signature type is defined in 6.4.3. 2115 CertificateVerify.signature.md5_hash 2116 MD5(handshake_messages); 2118 Certificate.signature.sha_hash 2119 SHA(handshake_messages); 2121 Here handshake_messages refers to all handshake messages sent or 2122 received starting at client hello up to but not including this 2123 message, including the type and length fields of the handshake 2124 messages. This is the concatenation of all the Handshake structures 2125 as defined in 7.4 exchanged thus far. 2127 7.4.9. Finished 2129 When this message will be sent: 2130 A finished message is always sent immediately after a change 2131 cipher spec message to verify that the key exchange and 2132 authentication processes were successful. It is essential that a 2133 change cipher spec message be received between the other 2134 handshake messages and the Finished message. 2136 Meaning of this message: 2137 The finished message is the first protected with the 2138 just-negotiated algorithms, keys, and secrets. Recipients of 2139 finished messages must verify that the contents are correct. 2140 Once a side has sent its Finished message and received and 2141 validated the Finished message from its peer, it may begin to 2142 send and receive application data over the connection. 2144 struct { 2145 opaque verify_data[12]; 2146 } Finished; 2147 verify_data 2148 PRF(master_secret, finished_label, MD5(handshake_messages) + 2149 SHA-1(handshake_messages)) [0..11]; 2151 finished_label 2152 For Finished messages sent by the client, the string "client 2153 finished". For Finished messages sent by the server, the 2154 string "server finished". 2156 handshake_messages 2157 All of the data from all handshake messages up to but not 2158 including this message. This is only data visible at the 2159 handshake layer and does not include record layer headers. 2160 This is the concatenation of all the Handshake structures as 2161 defined in 7.4 exchanged thus far. 2163 It is a fatal error if a finished message is not preceded by a 2164 change cipher spec message at the appropriate point in the 2165 handshake. 2167 The hash contained in finished messages sent by the server 2168 incorporate Sender.server; those sent by the client incorporate 2169 Sender.client. The value handshake_messages includes all handshake 2170 messages starting at client hello up to, but not including, this 2171 finished message. This may be different from handshake_messages in 2172 Section 7.4.8 because it would include the certificate verify 2173 message (if sent). Also, the handshake_messages for the finished 2174 message sent by the client will be different from that for the 2175 finished message sent by the server, because the one which is sent 2176 second will include the prior one. 2178 Note: Change cipher spec messages, alerts and any other record types 2179 are not handshake messages and are not included in the hash 2180 computations. Also, Hello Request messages are omitted from 2181 handshake hashes. 2183 8. Cryptographic computations 2185 In order to begin connection protection, the TLS Record Protocol 2186 requires specification of a suite of algorithms, a master secret, 2187 and the client and server random values. The authentication, 2188 encryption, and MAC algorithms are determined by the cipher_suite 2189 selected by the server and revealed in the server hello message. The 2190 compression algorithm is negotiated in the hello messages, and the 2191 random values are exchanged in the hello messages. All that remains 2192 is to calculate the master secret. 2194 8.1. Computing the master secret 2196 For all key exchange methods, the same algorithm is used to convert 2197 the pre_master_secret into the master_secret. The pre_master_secret 2198 should be deleted from memory once the master_secret has been 2199 computed. 2201 master_secret = PRF(pre_master_secret, "master secret", 2202 ClientHello.random + ServerHello.random) 2203 [0..47]; 2205 The master secret is always exactly 48 bytes in length. The length 2206 of the premaster secret will vary depending on key exchange method. 2208 8.1.1. RSA 2210 When RSA is used for server authentication and key exchange, a 2211 48-byte pre_master_secret is generated by the client, encrypted 2212 under the server's public key, and sent to the server. The server 2213 uses its private key to decrypt the pre_master_secret. Both parties 2214 then convert the pre_master_secret into the master_secret, as 2215 specified above. 2217 RSA digital signatures are performed using PKCS #1 [PKCS1] block 2218 type 1. RSA public key encryption is performed using PKCS #1 block 2219 type 2. 2221 8.1.2. Diffie-Hellman 2223 A conventional Diffie-Hellman computation is performed. The 2224 negotiated key (Z) is used as the pre_master_secret, and is 2225 converted into the master_secret, as specified above. 2227 Note: Diffie-Hellman parameters are specified by the server, and may 2228 be either ephemeral or contained within the server's 2229 certificate. 2231 9. Mandatory Cipher Suites 2233 In the absence of an application profile standard specifying 2234 otherwise, a TLS compliant application MUST implement the cipher 2235 suite TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA. 2237 10. Application data protocol 2239 Application data messages are carried by the Record Layer and are 2240 fragmented, compressed and encrypted based on the current connection 2241 state. The messages are treated as transparent data to the record 2242 layer. 2244 A. Protocol constant values 2246 This section describes protocol types and constants. 2248 A.1. Record layer 2250 struct { 2251 uint8 major, minor; 2252 } ProtocolVersion; 2254 ProtocolVersion version = { 3, 1 }; /* TLS v1.0 */ 2256 enum { 2257 change_cipher_spec(20), alert(21), handshake(22), 2258 application_data(23), (255) 2259 } ContentType; 2261 struct { 2262 ContentType type; 2263 ProtocolVersion version; 2264 uint16 length; 2265 opaque fragment[TLSPlaintext.length]; 2266 } TLSPlaintext; 2268 struct { 2269 ContentType type; 2270 ProtocolVersion version; 2271 uint16 length; 2272 opaque fragment[TLSCompressed.length]; 2273 } TLSCompressed; 2275 struct { 2276 ContentType type; 2277 ProtocolVersion version; 2278 uint16 length; 2279 select (CipherSpec.cipher_type) { 2280 case stream: GenericStreamCipher; 2281 case block: GenericBlockCipher; 2282 } fragment; 2283 } TLSCiphertext; 2285 stream-ciphered struct { 2286 opaque content[TLSCompressed.length]; 2287 opaque MAC[CipherSpec.hash_size]; 2288 } GenericStreamCipher; 2290 block-ciphered struct { 2291 opaque content[TLSCompressed.length]; 2292 opaque MAC[CipherSpec.hash_size]; 2293 uint8 padding[GenericBlockCipher.padding_length]; 2294 uint8 padding_length; 2295 } GenericBlockCipher; 2297 A.2. Change cipher specs message 2299 struct { 2300 enum { change_cipher_spec(1), (255) } type; 2301 } ChangeCipherSpec; 2303 A.3. Alert messages 2305 enum { warning(1), fatal(2), (255) } AlertLevel; 2307 enum { 2308 close_notify(0), 2309 unexpected_message(10), 2310 bad_record_mac(20), 2311 decryption_failed(21), 2312 record_overflow(22), 2313 decompression_failure(30), 2314 handshake_failure(40), 2315 bad_certificate(42), 2316 unsupported_certificate(43), 2317 certificate_revoked(44), 2318 certificate_expired(45), 2319 certificate_unknown(46), 2320 illegal_parameter(47), 2321 unknown_ca(48), 2322 access_denied(49), 2323 decode_error(50), 2324 decrypt_error(51), 2325 export_restriction(60), 2326 protocol_version(70), 2327 insufficient_security(71), 2328 internal_error(80), 2329 user_canceled(90), 2330 no_renegotiation(100), 2331 (255) 2332 } AlertDescription; 2334 struct { 2335 AlertLevel level; 2336 AlertDescription description; 2337 } Alert; 2339 A.4. Handshake protocol 2341 enum { 2342 hello_request(0), client_hello(1), server_hello(2), 2343 certificate(11), server_key_exchange (12), 2344 certificate_request(13), server_hello_done(14), 2345 certificate_verify(15), client_key_exchange(16), 2346 finished(20), (255) 2347 } HandshakeType; 2349 struct { 2350 HandshakeType msg_type; 2351 uint24 length; 2352 select (HandshakeType) { 2353 case hello_request: HelloRequest; 2354 case client_hello: ClientHello; 2355 case server_hello: ServerHello; 2356 case certificate: Certificate; 2357 case server_key_exchange: ServerKeyExchange; 2358 case certificate_request: CertificateRequest; 2359 case server_hello_done: ServerHelloDone; 2360 case certificate_verify: CertificateVerify; 2361 case client_key_exchange: ClientKeyExchange; 2362 case finished: Finished; 2363 } body; 2364 } Handshake; 2366 A.4.1. Hello messages 2368 struct { } HelloRequest; 2370 struct { 2371 uint32 gmt_unix_time; 2372 opaque random_bytes[28]; 2373 } Random; 2375 opaque SessionID<0..32>; 2377 uint8 CipherSuite[2]; 2379 enum { null(0), (255) } CompressionMethod; 2381 struct { 2382 ProtocolVersion client_version; 2383 Random random; 2384 SessionID session_id; 2385 CipherSuite cipher_suites<2..2^16-1>; 2386 CompressionMethod compression_methods<0..2^8-1>; 2387 } ClientHello; 2389 struct { 2390 ProtocolVersion server_version; 2391 Random random; 2392 SessionID session_id; 2393 CipherSuite cipher_suite; 2394 CompressionMethod compression_method; 2395 } ServerHello; 2397 A.4.2. Server authentication and key exchange messages 2399 opaque ASN.1Cert<2^24-1>; 2401 struct { 2402 ASN.1Cert certificate_list<1..2^24-1>; 2403 } Certificate; 2405 enum { rsa, diffie_hellman } KeyExchangeAlgorithm; 2406 struct { 2407 opaque RSA_modulus<1..2^16-1>; 2408 opaque RSA_exponent<1..2^16-1>; 2409 } ServerRSAParams; 2411 struct { 2412 opaque DH_p<1..2^16-1>; 2413 opaque DH_g<1..2^16-1>; 2414 opaque DH_Ys<1..2^16-1>; 2415 } ServerDHParams; 2417 struct { 2418 select (KeyExchangeAlgorithm) { 2419 case diffie_hellman: 2420 ServerDHParams params; 2421 Signature signed_params; 2422 case rsa: 2423 ServerRSAParams params; 2424 Signature signed_params; 2425 }; 2426 } ServerKeyExchange; 2428 enum { anonymous, rsa, dsa } SignatureAlgorithm; 2430 select (SignatureAlgorithm) 2431 { case anonymous: struct { }; 2432 case rsa: 2433 digitally-signed struct { 2434 opaque md5_hash[16]; 2435 opaque sha_hash[20]; 2436 }; 2437 case dsa: 2438 digitally-signed struct { 2439 opaque sha_hash[20]; 2440 }; 2441 } Signature; 2443 enum { 2444 rsa_sign(1), dss_sign(2), rsa_fixed_dh(3), dss_fixed_dh(4), 2445 (255) 2446 } ClientCertificateType; 2448 opaque DistinguishedName<1..2^16-1>; 2450 struct { 2451 ClientCertificateType certificate_types<1..2^8-1>; 2452 DistinguishedName certificate_authorities<3..2^16-1>; 2453 } CertificateRequest; 2455 struct { } ServerHelloDone; 2457 A.4.3. Client authentication and key exchange messages 2459 struct { 2460 select (KeyExchangeAlgorithm) { 2461 case rsa: EncryptedPreMasterSecret; 2462 case diffie_hellman: DiffieHellmanClientPublicValue; 2463 } exchange_keys; 2464 } ClientKeyExchange; 2466 struct { 2467 ProtocolVersion client_version; 2468 opaque random[46]; 2469 } PreMasterSecret; 2471 struct { 2472 public-key-encrypted PreMasterSecret pre_master_secret; 2473 } EncryptedPreMasterSecret; 2475 enum { implicit, explicit } PublicValueEncoding; 2477 struct { 2478 select (PublicValueEncoding) { 2479 case implicit: struct {}; 2480 case explicit: opaque DH_Yc<1..2^16-1>; 2481 } dh_public; 2482 } ClientDiffieHellmanPublic; 2484 struct { 2485 Signature signature; 2486 } CertificateVerify; 2488 A.4.4. Handshake finalization message 2490 struct { 2491 opaque verify_data[12]; 2492 } Finished; 2494 A.5. The CipherSuite 2496 The following values define the CipherSuite codes used in the client 2497 hello and server hello messages. 2499 A CipherSuite defines a cipher specification supported in TLS 2500 Version 1.0. 2502 TLS_NULL_WITH_NULL_NULL is specified and is the initial state of a 2503 TLS connection during the first handshake on that channel, but must 2504 not be negotiated, as it provides no more protection than an 2505 unsecured connection. 2507 CipherSuite TLS_NULL_WITH_NULL_NULL = { 0x00,0x00 }; 2509 The following CipherSuite definitions require that the server 2510 provide an RSA certificate that can be used for key exchange. The 2511 server may request either an RSA or a DSS signature-capable 2512 certificate in the certificate request message. 2514 CipherSuite TLS_RSA_WITH_NULL_MD5 = { 0x00,0x01 }; 2515 CipherSuite TLS_RSA_WITH_NULL_SHA = { 0x00,0x02 }; 2516 CipherSuite TLS_RSA_EXPORT_WITH_RC4_40_MD5 = { 0x00,0x03 }; 2517 CipherSuite TLS_RSA_WITH_RC4_128_MD5 = { 0x00,0x04 }; 2518 CipherSuite TLS_RSA_WITH_RC4_128_SHA = { 0x00,0x05 }; 2519 CipherSuite TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 = { 0x00,0x06 }; 2520 CipherSuite TLS_RSA_WITH_IDEA_CBC_SHA = { 0x00,0x07 }; 2521 CipherSuite TLS_RSA_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x08 }; 2522 CipherSuite TLS_RSA_WITH_DES_CBC_SHA = { 0x00,0x09 }; 2523 CipherSuite TLS_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x0A }; 2525 The following CipherSuite definitions are used for 2526 server-authenticated (and optionally client-authenticated) 2527 Diffie-Hellman. DH denotes cipher suites in which the server's 2528 certificate contains the Diffie-Hellman parameters signed by the 2529 certificate authority (CA). DHE denotes ephemeral Diffie-Hellman, 2530 where the Diffie-Hellman parameters are signed by a DSS or RSA 2531 certificate, which has been signed by the CA. The signing algorithm 2532 used is specified after the DH or DHE parameter. The server can 2533 request an RSA or DSS signature-capable certificate from the client 2534 for client authentication or it may request a Diffie-Hellman 2535 certificate. Any Diffie-Hellman certificate provided by the client 2536 must use the parameters (group and generator) described by the 2537 server. 2539 CipherSuite TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x0B }; 2540 CipherSuite TLS_DH_DSS_WITH_DES_CBC_SHA = { 0x00,0x0C }; 2541 CipherSuite TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA = { 0x00,0x0D }; 2542 CipherSuite TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x0E }; 2543 CipherSuite TLS_DH_RSA_WITH_DES_CBC_SHA = { 0x00,0x0F }; 2544 CipherSuite TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x10 }; 2545 CipherSuite TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x11 }; 2546 CipherSuite TLS_DHE_DSS_WITH_DES_CBC_SHA = { 0x00,0x12 }; 2547 CipherSuite TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA = { 0x00,0x13 }; 2548 CipherSuite TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x14 }; 2549 CipherSuite TLS_DHE_RSA_WITH_DES_CBC_SHA = { 0x00,0x15 }; 2550 CipherSuite TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x16 }; 2552 The following cipher suites are used for completely anonymous 2553 Diffie-Hellman communications in which neither party is 2554 authenticated. Note that this mode is vulnerable to 2555 man-in-the-middle attacks and is therefore deprecated. 2557 CipherSuite TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 = { 0x00,0x17 }; 2558 CipherSuite TLS_DH_anon_WITH_RC4_128_MD5 = { 0x00,0x18 }; 2559 CipherSuite TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x19 }; 2560 CipherSuite TLS_DH_anon_WITH_DES_CBC_SHA = { 0x00,0x1A }; 2561 CipherSuite TLS_DH_anon_WITH_3DES_EDE_CBC_SHA = { 0x00,0x1B }; 2563 Note: All cipher suites whose first byte is 0xFF are considered 2564 private and can be used for defining local/experimental 2565 algorithms. Interoperability of such types is a local matter. 2567 Note: Additional cipher suites will be considered for implementation 2568 only with submission of notarized letters from two independent 2569 entities. Consensus Development Corp. will act as an interim 2570 registration office, until a public standards body assumes 2571 control of TLS cipher suites. 2573 A.6. The Security Parameters 2575 These security parameters are determined by the TLS Handshake 2576 Protocol and provided as parameters to the TLS Record Layer in order 2577 to initialize a connection state. SecurityParameters includes: 2579 enum { null(0), (255) } CompressionMethod; 2581 enum { server, client } ConnectionEnd; 2583 enum { null, rc4, rc2, des, 3des, des40, idea } 2584 BulkCipherAlgorithm; 2586 enum { stream, block } CipherType; 2588 enum { true, false } IsExportable; 2590 enum { null, md5, sha } MACAlgorithm; 2592 /* The algorithms specified in CompressionMethod, 2593 BulkCipherAlgorithm, and MACAlgorithm may be added to. */ 2595 struct { 2596 ConnectionEnd entity; 2597 BulkCipherAlgorithm bulk_cipher_algorithm; 2598 CipherType cipher_type; 2599 uint8 key_size; 2600 uint8 key_material_length; 2601 IsExportable is_exportable; 2602 MACAlgorithm mac_algorithm; 2603 uint8 hash_size; 2604 CompressionMethod compression_algorithm; 2605 opaque master_secret[48]; 2606 opaque client_random[32]; 2607 opaque server_random[32]; 2608 } SecurityParameters; 2610 B. Glossary 2612 application protocol 2613 An application protocol is a protocol that normally layers 2614 directly on top of the transport layer (e.g., TCP/IP). Examples 2615 include HTTP, TELNET, FTP, and SMTP. 2617 asymmetric cipher 2618 See public key cryptography. 2620 authentication 2621 Authentication is the ability of one entity to determine the 2622 identity of another entity. 2624 block cipher 2625 A block cipher is an algorithm that operates on plaintext in 2626 groups of bits, called blocks. 64 bits is a common block size. 2628 bulk cipher 2629 A symmetric encryption algorithm used to encrypt large 2630 quantities of data. 2632 cipher block chaining (CBC) 2633 CBC is a mode in which every plaintext block encrypted with a 2634 block cipher is first exclusive-ORed with the previous 2635 ciphertext block (or, in the case of the first block, with the 2636 initialization vector). For decryption, every block is first 2637 decrypted, then exclusive-ORed with the previous ciphertext 2638 block (or IV). 2640 certificate 2641 As part of the X.509 protocol (a.k.a. ISO Authentication 2642 framework), certificates are assigned by a trusted Certificate 2643 Authority and provide a strong binding between a party's 2644 identity or some other attributes and its public key. 2646 client 2647 The application entity that initiates a TLS connection to a 2648 server. This may or may not imply that the client initiated the 2649 underlying transport connection. The primary operational 2650 difference between the server and client is that the server is 2651 generally authenticated, while the client is only optionally 2652 authenticated. 2654 client write key 2655 The key used to encrypt data written by the client. 2657 client write MAC secret 2658 The secret data used to authenticate data written by the client. 2660 connection 2661 A connection is a transport (in the OSI layering model 2662 definition) that provides a suitable type of service. For TLS, 2663 such connections are peer to peer relationships. The connections 2664 are transient. Every connection is associated with one session. 2666 Data Encryption Standard 2667 DES is a very widely used symmetric encryption algorithm. DES is 2668 a block cipher with a 56 bit key and an 8 byte block size. Note 2669 that in TLS, for key generation purposes, DES is treated as 2670 having an 8 byte key length (64 bits), but it still only 2671 provides 56 bits of protection. DES can also be operated in a 2672 mode where three independent keys and three encryptions are used 2673 for each block of data; this uses 168 bits of key (24 bytes in 2674 the TLS key generation method) and provides the equivalent of 2675 112 bits of security. [DES], [3DES] 2677 Digital Signature Standard (DSS) 2678 A standard for digital signing, including the Digital Signing 2679 Algorithm, approved by the National Institute of Standards and 2680 Technology, defined in NIST FIPS PUB 186, "Digital Signature 2681 Standard," published May, 1994 by the U.S. Dept. of Commerce. 2682 [DSS] 2684 digital signatures 2685 Digital signatures utilize public key cryptography and one-way 2686 hash functions to produce a signature of the data that can be 2687 authenticated, and is difficult to forge or repudiate. 2689 handshake 2690 An initial negotiation between client and server that 2691 establishes the parameters of their transactions. 2693 Initialization Vector (IV) 2694 When a block cipher is used in CBC mode, the initialization 2695 vector is exclusive-ORed with the first plaintext block prior to 2696 encryption. 2698 IDEA 2699 A 64-bit block cipher designed by Xuejia Lai and James Massey. 2700 [IDEA] 2702 Message Authentication Code (MAC) 2703 A Message Authentication Code is a one-way hash computed from a 2704 message and some secret data. It is difficult to forge without 2705 knowing the secret data. Its purpose is to detect if the message 2706 has been altered. 2708 master secret 2709 Secure secret data used for generating encryption keys, MAC 2710 secrets, and IVs. 2712 MD5 2713 MD5 is a secure hashing function that converts an arbitrarily 2714 long data stream into a digest of fixed size (16 bytes). [MD5] 2716 public key cryptography 2717 A class of cryptographic techniques employing two-key ciphers. 2718 Messages encrypted with the public key can only be decrypted 2719 with the associated private key. Conversely, messages signed 2720 with the private key can be verified with the public key. 2722 one-way hash function 2723 A one-way transformation that converts an arbitrary amount of 2724 data into a fixed-length hash. It is computationally hard to 2725 reverse the transformation or to find collisions. MD5 and SHA 2726 are examples of one-way hash functions. 2728 RC2 2729 A block cipher developed by Ron Rivest at RSA Data Security, 2730 Inc. [RSADSI] described in [RC2]. 2732 RC4 2733 A stream cipher licensed by RSA Data Security [RSADSI]. A 2734 compatible cipher is described in [RC4]. 2736 RSA 2737 A very widely used public-key algorithm that can be used for 2738 either encryption or digital signing. [RSA] 2740 salt 2741 Non-secret random data used to make export encryption keys 2742 resist precomputation attacks. 2744 server 2745 The server is the application entity that responds to requests 2746 for connections from clients. See also under client. 2748 session 2749 A TLS session is an association between a client and a server. 2750 Sessions are created by the handshake protocol. Sessions define 2751 a set of cryptographic security parameters, which can be shared 2752 among multiple connections. Sessions are used to avoid the 2753 expensive negotiation of new security parameters for each 2754 connection. 2756 session identifier 2757 A session identifier is a value generated by a server that 2758 identifies a particular session. 2760 server write key 2761 The key used to encrypt data written by the server. 2763 server write MAC secret 2764 The secret data used to authenticate data written by the server. 2766 SHA 2767 The Secure Hash Algorithm is defined in FIPS PUB 180-1. It 2768 produces a 20-byte output. Note that all references to SHA 2769 actually use the modified SHA-1 algorithm. [SHA] 2771 SSL 2772 Netscape's Secure Socket Layer protocol [SSL3]. TLS is based on 2773 SSL Version 3.0 2775 stream cipher 2776 An encryption algorithm that converts a key into a 2777 cryptographically-strong keystream, which is then exclusive-ORed 2778 with the plaintext. 2780 symmetric cipher 2781 See bulk cipher. 2783 Transport Layer Security (TLS) 2784 This protocol; also, the Transport Layer Security working group 2785 of the Internet Engineering Task Force (IETF). See "Comments" at 2786 the end of this document. 2788 C. CipherSuite definitions 2790 CipherSuite Is Key Cipher Hash 2791 Exportable Exchange 2793 TLS_NULL_WITH_NULL_NULL * NULL NULL NULL 2794 TLS_RSA_WITH_NULL_MD5 * RSA NULL MD5 2795 TLS_RSA_WITH_NULL_SHA * RSA NULL SHA 2796 TLS_RSA_EXPORT_WITH_RC4_40_MD5 * RSA_EXPORT RC4_40 MD5 2797 TLS_RSA_WITH_RC4_128_MD5 RSA RC4_128 MD5 2798 TLS_RSA_WITH_RC4_128_SHA RSA RC4_128 SHA 2799 TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 * RSA_EXPORT RC2_CBC_40 MD5 2800 TLS_RSA_WITH_IDEA_CBC_SHA RSA IDEA_CBC SHA 2801 TLS_RSA_EXPORT_WITH_DES40_CBC_SHA * RSA_EXPORT DES40_CBC SHA 2802 TLS_RSA_WITH_DES_CBC_SHA RSA DES_CBC SHA 2803 TLS_RSA_WITH_3DES_EDE_CBC_SHA RSA 3DES_EDE_CBC SHA 2804 TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA * DH_DSS_EXPORT DES40_CBC SHA 2805 TLS_DH_DSS_WITH_DES_CBC_SHA DH_DSS DES_CBC SHA 2806 TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA DH_DSS 3DES_EDE_CBC SHA 2807 TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA * DH_RSA_EXPORT DES40_CBC SHA 2808 TLS_DH_RSA_WITH_DES_CBC_SHA DH_RSA DES_CBC SHA 2809 TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA DH_RSA 3DES_EDE_CBC SHA 2810 TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA * DHE_DSS_EXPORT DES40_CBC SHA 2811 TLS_DHE_DSS_WITH_DES_CBC_SHA DHE_DSS DES_CBC SHA 2812 TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE_DSS 3DES_EDE_CBC SHA 2813 TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA * DHE_RSA_EXPORT DES40_CBC SHA 2814 TLS_DHE_RSA_WITH_DES_CBC_SHA DHE_RSA DES_CBC SHA 2815 TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE_RSA 3DES_EDE_CBC SHA 2816 TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 * DH_anon_EXPORT RC4_40 MD5 2817 TLS_DH_anon_WITH_RC4_128_MD5 DH_anon RC4_128 MD5 2818 TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA DH_anon DES40_CBC SHA 2819 TLS_DH_anon_WITH_DES_CBC_SHA DH_anon DES_CBC SHA 2820 TLS_DH_anon_WITH_3DES_EDE_CBC_SHA DH_anon 3DES_EDE_CBC SHA 2822 * Indicates IsExportable is True 2824 Key 2825 Exchange 2826 Algorithm Description Key size limit 2828 DHE_DSS Ephemeral DH with DSS signatures None 2829 DHE_DSS_EXPORT Ephemeral DH with DSS signatures DH = 512 bits 2830 DHE_RSA Ephemeral DH with RSA signatures None 2831 DHE_RSA_EXPORT Ephemeral DH with RSA signatures DH = 512 bits, 2832 RSA = none 2833 DH_anon Anonymous DH, no signatures None 2834 DH_anon_EXPORT Anonymous DH, no signatures DH = 512 bits 2835 DH_DSS DH with DSS-based certificates None 2836 DH_DSS_EXPORT DH with DSS-based certificates DH = 512 bits 2837 DH_RSA DH with RSA-based certificates None 2838 DH_RSA_EXPORT DH with RSA-based certificates DH = 512 bits, 2839 RSA = none 2840 NULL No key exchange N/A 2841 RSA RSA key exchange None 2842 RSA_EXPORT RSA key exchange RSA = 512 bits 2844 Key size limit 2845 The key size limit gives the size of the largest public key that 2846 can be legally used for encryption in cipher suites that are 2847 exportable. 2849 Key Expanded Effective IV Block 2850 Cipher Type Material Key Material Key Bits Size Size 2852 NULL * Stream 0 0 0 0 N/A 2853 IDEA_CBC Block 16 16 128 8 8 2854 RC2_CBC_40 * Block 5 16 40 8 8 2855 RC4_40 * Stream 5 16 40 0 N/A 2856 RC4_128 Stream 16 16 128 0 N/A 2857 DES40_CBC * Block 5 8 40 8 8 2858 DES_CBC Block 8 8 56 8 8 2859 3DES_EDE_CBC Block 24 24 168 8 8 2861 * Indicates IsExportable is true. 2863 Type 2864 Indicates whether this is a stream cipher or a block cipher 2865 running in CBC mode. 2867 Key Material 2868 The number of bytes from the key_block that are used for 2869 generating the write keys. 2871 Expanded Key Material 2872 The number of bytes actually fed into the encryption algorithm 2874 Effective Key Bits 2875 How much entropy material is in the key material being fed into 2876 the encryption routines. 2878 IV Size 2879 How much data needs to be generated for the initialization 2880 vector. Zero for stream ciphers; equal to the block size for 2881 block ciphers. 2883 Block Size 2884 The amount of data a block cipher enciphers in one chunk; a 2885 block cipher running in CBC mode can only encrypt an even 2886 multiple of its block size. 2888 Hash Hash Padding 2889 function Size Size 2890 NULL 0 0 2891 MD5 16 48 2892 SHA 20 40 2894 Appendix D 2896 D. Implementation Notes 2898 The TLS protocol cannot prevent many common security mistakes. This 2899 section provides several recommendations to assist implementors. 2901 D.1. Temporary RSA keys 2903 US Export restrictions limit RSA keys used for encryption to 512 2904 bits, but do not place any limit on lengths of RSA keys used for 2905 signing operations. Certificates often need to be larger than 512 2906 bits, since 512-bit RSA keys are not secure enough for high-value 2907 transactions or for applications requiring long-term security. Some 2908 certificates are also designated signing-only, in which case they 2909 cannot be used for key exchange. 2911 When the public key in the certificate cannot be used for 2912 encryption, the server signs a temporary RSA key, which is then 2913 exchanged. In exportable applications, the temporary RSA key should 2914 be the maximum allowable length (i.e., 512 bits). Because 512-bit 2915 RSA keys are relatively insecure, they should be changed often. For 2916 typical electronic commerce applications, it is suggested that keys 2917 be changed daily or every 500 transactions, and more often if 2918 possible. Note that while it is acceptable to use the same temporary 2919 key for multiple transactions, it must be signed each time it is 2920 used. 2922 RSA key generation is a time-consuming process. In many cases, a 2923 low-priority process can be assigned the task of key generation. 2925 Whenever a new key is completed, the existing temporary key can be 2926 replaced with the new one. 2928 D.2. Random Number Generation and Seeding 2930 TLS requires a cryptographically-secure pseudorandom number 2931 generator (PRNG). Care must be taken in designing and seeding PRNGs. 2932 PRNGs based on secure hash operations, most notably MD5 and/or SHA, 2933 are acceptable, but cannot provide more security than the size of 2934 the random number generator state. (For example, MD5-based PRNGs 2935 usually provide 128 bits of state.) 2937 To estimate the amount of seed material being produced, add the 2938 number of bits of unpredictable information in each seed byte. For 2939 example, keystroke timing values taken from a PC compatible's 18.2 2940 Hz timer provide 1 or 2 secure bits each, even though the total size 2941 of the counter value is 16 bits or more. To seed a 128-bit PRNG, one 2942 would thus require approximately 100 such timer values. 2944 Warning: The seeding functions in RSAREF and versions of BSAFE prior to 2945 3.0 are order-independent. For example, if 1000 seed bits are 2946 supplied, one at a time, in 1000 separate calls to the seed 2947 function, the PRNG will end up in a state which depends only 2948 on the number of 0 or 1 seed bits in the seed data (i.e., 2949 there are 1001 possible final states). Applications using 2950 BSAFE or RSAREF must take extra care to ensure proper seeding. 2951 This may be accomplished by accumulating seed bits into a 2952 buffer and processing them all at once or by processing an 2953 incrementing counter with every seed bit; either method will 2954 reintroduce order dependence into the seeding process. 2956 D.3. Certificates and authentication 2958 Implementations are responsible for verifying the integrity of 2959 certificates and should generally support certificate revocation 2960 messages. Certificates should always be verified to ensure proper 2961 signing by a trusted Certificate Authority (CA). The selection and 2962 addition of trusted CAs should be done very carefully. Users should 2963 be able to view information about the certificate and root CA. 2965 D.4. CipherSuites 2967 TLS supports a range of key sizes and security levels, including 2968 some which provide no or minimal security. A proper implementation 2969 will probably not support many cipher suites. For example, 40-bit 2970 encryption is easily broken, so implementations requiring strong 2971 security should not allow 40-bit keys. Similarly, anonymous 2972 Diffie-Hellman is strongly discouraged because it cannot prevent 2973 man-in-the-middle attacks. Applications should also enforce minimum 2974 and maximum key sizes. For example, certificate chains containing 2975 512-bit RSA keys or signatures are not appropriate for high-security 2976 applications. 2978 E. Backward Compatibility With SSL 2980 For historical reasons and in order to avoid a profligate 2981 consumption of reserved port numbers, application protocols which 2982 are secured by TLS 1.0, SSL 3.0, and SSL 2.0 all frequently share 2983 the same connection port: for example, the https protocol (HTTP 2984 secured by SSL or TLS) uses port 443 regardless of which security 2985 protocol it is using. Thus, some mechanism must be determined to 2986 distinguish and negotiate among the various protocols. 2988 TLS version 1.0 and SSL 3.0 are very similar; thus, supporting both 2989 is easy. TLS clients who wish to negotiate with SSL 3.0 servers 2990 should send client hello messages using the SSL 3.0 record format 2991 and client hello structure, sending {3, 1} for the version field to 2992 note that they support TLS 1.0. If the server supports only SSL 3.0, 2993 it will respond with an SSL 3.0 server hello; if it supports TLS, 2994 with a TLS server hello. The negotiation then proceeds as 2995 appropriate for the negotiated protocol. 2997 Similarly, a TLS server which wishes to interoperate with SSL 3.0 2998 clients should accept SSL 3.0 client hello messages and respond with 2999 an SSL 3.0 server hello if an SSL 3.0 client hello is received which 3000 has a version field of {3, 0}, denoting that this client does not 3001 support TLS. 3003 Whenever a client already knows the highest protocol known to a 3004 server (for example, when resuming a session), it should initiate 3005 the connection in that native protocol. 3007 TLS 1.0 clients that support SSL Version 2.0 servers must send SSL 3008 Version 2.0 client hello messages [SSL2]. TLS servers should accept 3009 either client hello format if they wish to support SSL 2.0 clients 3010 on the same connection port. The only deviations from the Version 3011 2.0 specification are the ability to specify a version with a value 3012 of three and the support for more ciphering types in the CipherSpec. 3014 Warning: The ability to send Version 2.0 client hello messages will be 3015 phased out with all due haste. Implementors should make every 3016 effort to move forward as quickly as possible. Version 3.0 3017 provides better mechanisms for moving to newer versions. 3019 The following cipher specifications are carryovers from SSL Version 3020 2.0. These are assumed to use RSA for key exchange and 3021 authentication. 3023 V2CipherSpec TLS_RC4_128_WITH_MD5 = { 0x01,0x00,0x80 }; 3024 V2CipherSpec TLS_RC4_128_EXPORT40_WITH_MD5 = { 0x02,0x00,0x80 }; 3025 V2CipherSpec TLS_RC2_CBC_128_CBC_WITH_MD5 = { 0x03,0x00,0x80 }; 3026 V2CipherSpec TLS_RC2_CBC_128_CBC_EXPORT40_WITH_MD5 3027 = { 0x04,0x00,0x80 }; 3028 V2CipherSpec TLS_IDEA_128_CBC_WITH_MD5 = { 0x05,0x00,0x80 }; 3029 V2CipherSpec TLS_DES_64_CBC_WITH_MD5 = { 0x06,0x00,0x40 }; 3030 V2CipherSpec TLS_DES_192_EDE3_CBC_WITH_MD5 = { 0x07,0x00,0xC0 }; 3032 Cipher specifications native to TLS can be included in Version 2.0 3033 client hello messages using the syntax below. Any V2CipherSpec 3034 element with its first byte equal to zero will be ignored by Version 3035 2.0 servers. Clients sending any of the above V2CipherSpecs should 3036 also include the TLS equivalent (see Appendix A.6): 3038 V2CipherSpec (see TLS name) = { 0x00, CipherSuite }; 3040 E.1. Version 2 client hello 3042 The Version 2.0 client hello message is presented below using this 3043 document's presentation model. The true definition is still assumed 3044 to be the SSL Version 2.0 specification. 3046 uint8 V2CipherSpec[3]; 3048 struct { 3049 unit8 msg_type; 3050 Version version; 3051 uint16 cipher_spec_length; 3052 uint16 session_id_length; 3053 uint16 challenge_length; 3054 V2CipherSpec cipher_specs[V2ClientHello.cipher_spec_length]; 3055 opaque session_id[V2ClientHello.session_id_length]; 3056 Random challenge; 3057 } V2ClientHello; 3059 msg_type 3060 This field, in conjunction with the version field, identifies a 3061 version 2 client hello message. The value should be one (1). 3063 version 3064 The highest version of the protocol supported by the client 3065 (equals ProtocolVersion.version, see Appendix A.1.1). 3067 cipher_spec_length 3068 This field is the total length of the field cipher_specs. It 3069 cannot be zero and must be a multiple of the V2CipherSpec length 3070 (3). 3072 session_id_length 3073 This field must have a value of either zero or 16. If zero, the 3074 client is creating a new session. If 16, the session_id field 3075 will contain the 16 bytes of session identification. 3077 challenge_length 3078 The length in bytes of the client's challenge to the server to 3079 authenticate itself. This value must be 32. 3081 cipher_specs 3082 This is a list of all CipherSpecs the client is willing and able 3083 to use. There must be at least one CipherSpec acceptable to the 3084 server. 3086 session_id 3087 If this field's length is not zero, it will contain the 3088 identification for a session that the client wishes to resume. 3090 challenge 3091 The client challenge to the server for the server to identify 3092 itself is a (nearly) arbitrary length random. The Version 3.0 3093 server will right justify the challenge data to become the 3094 ClientHello.random data (padded with leading zeroes, if 3095 necessary), as specified in this Version 3.0 protocol. If the 3096 length of the challenge is greater than 32 bytes, only the last 3097 32 bytes are used. It is legitimate (but not necessary) for a V3 3098 server to reject a V2 ClientHello that has fewer than 16 bytes 3099 of challenge data. 3101 Note: Requests to resume a TLS session should use a TLS client hello. 3103 E.2. Avoiding man-in-the-middle version rollback 3105 When TLS clients fall back to Version 2.0 compatibility mode, they 3106 should use special PKCS #1 block formatting. This is done so that 3107 TLS servers will reject Version 2.0 sessions with TLS-capable 3108 clients. 3110 When TLS clients are in Version 2.0 compatibility mode, they set the 3111 right-hand (least-significant) 8 random bytes of the PKCS padding 3112 (not including the terminal null of the padding) for the RSA 3113 encryption of the ENCRYPTED-KEY-DATA field of the CLIENT-MASTER-KEY 3114 to 0x03 (the other padding bytes are random). After decrypting the 3115 ENCRYPTED-KEY-DATA field, servers that support TLS should issue an 3116 error if these eight padding bytes are 0x03. Version 2.0 servers 3117 receiving blocks padded in this manner will proceed normally. 3119 Appendix F 3121 F. Security analysis 3123 The TLS protocol is designed to establish a secure connection 3124 between a client and a server communicating over an insecure 3125 channel. This document makes several traditional assumptions, 3126 including that attackers have substantial computational resources 3127 and cannot obtain secret information from sources outside the 3128 protocol. Attackers are assumed to have the ability to capture, 3129 modify, delete, replay, and otherwise tamper with messages sent over 3130 the communication channel. This appendix outlines how TLS has been 3131 designed to resist a variety of attacks. 3133 F.1. Handshake protocol 3135 The handshake protocol is responsible for selecting a CipherSpec and 3136 generating a Master Secret, which together comprise the primary 3137 cryptographic parameters associated with a secure session. The 3138 handshake protocol can also optionally authenticate parties who have 3139 certificates signed by a trusted certificate authority. 3141 F.1.1. Authentication and key exchange 3143 TLS supports three authentication modes: authentication of both 3144 parties, server authentication with an unauthenticated client, and 3145 total anonymity. Whenever the server is authenticated, the channel 3146 is secure against man-in-the-middle attacks, but completely 3147 anonymous sessions are inherently vulnerable to such attacks. 3148 Anonymous servers cannot authenticate clients. If the server is 3149 authenticated, its certificate message must provide a valid 3150 certificate chain leading to an acceptable certificate authority. 3151 Similarly, authenticated clients must supply an acceptable 3152 certificate to the server. Each party is responsible for verifying 3153 that the other's certificate is valid and has not expired or been 3154 revoked. 3156 The general goal of the key exchange process is to create a 3157 pre_master_secret known to the communicating parties and not to 3158 attackers. The pre_master_secret will be used to generate the 3159 master_secret (see Section 8.1). The master_secret is required to 3160 generate the certificate verify and finished messages, encryption 3161 keys, and MAC secrets (see Sections 7.4.8, 7.4.9 and 6.3). By 3162 sending a correct finished message, parties thus prove that they 3163 know the correct pre_master_secret. 3165 F.1.1.1. Anonymous key exchange 3167 Completely anonymous sessions can be established using RSA or 3168 Diffie-Hellman for key exchange. With anonymous RSA, the client 3169 encrypts a pre_master_secret with the server's uncertified public 3170 key extracted from the server key exchange message. The result is 3171 sent in a client key exchange message. Since eavesdroppers do not 3172 know the server's private key, it will be infeasible for them to 3173 decode the pre_master_secret. (Note that no anonymous RSA Cipher 3174 Suites are defined in this document). 3176 With Diffie-Hellman, the server's public parameters are contained in 3177 the server key exchange message and the client's are sent in the 3178 client key exchange message. Eavesdroppers who do not know the 3179 private values should not be able to find the Diffie-Hellman result 3180 (i.e. the pre_master_secret). 3182 Warning: Completely anonymous connections only provide protection 3183 against passive eavesdropping. Unless an independent 3184 tamper-proof channel is used to verify that the finished 3185 messages were not replaced by an attacker, server 3186 authentication is required in environments where active 3187 man-in-the-middle attacks are a concern. 3189 F.1.1.2. RSA key exchange and authentication 3191 With RSA, key exchange and server authentication are combined. The 3192 public key may be either contained in the server's certificate or 3193 may be a temporary RSA key sent in a server key exchange message. 3194 When temporary RSA keys are used, they are signed by the server's 3195 RSA or DSS certificate. The signature includes the current 3196 ClientHello.random, so old signatures and temporary keys cannot be 3197 replayed. Servers may use a single temporary RSA key for multiple 3198 negotiation sessions. 3200 Note: The temporary RSA key option is useful if servers need large 3201 certificates but must comply with government-imposed size limits 3202 on keys used for key exchange. 3204 After verifying the server's certificate, the client encrypts a 3205 pre_master_secret with the server's public key. By successfully 3206 decoding the pre_master_secret and producing a correct finished 3207 message, the server demonstrates that it knows the private key 3208 corresponding to the server certificate. 3210 When RSA is used for key exchange, clients are authenticated using 3211 the certificate verify message (see Section 7.4.8). The client signs 3212 a value derived from the master_secret and all preceding handshake 3213 messages. These handshake messages include the server certificate, 3214 which binds the signature to the server, and ServerHello.random, 3215 which binds the signature to the current handshake process. 3217 F.1.1.3. Diffie-Hellman key exchange with authentication 3219 When Diffie-Hellman key exchange is used, the server can either 3220 supply a certificate containing fixed Diffie-Hellman parameters or 3221 can use the server key exchange message to send a set of temporary 3222 Diffie-Hellman parameters signed with a DSS or RSA certificate. 3223 Temporary parameters are hashed with the hello.random values before 3224 signing to ensure that attackers do not replay old parameters. In 3225 either case, the client can verify the certificate or signature to 3226 ensure that the parameters belong to the server. 3228 If the client has a certificate containing fixed Diffie-Hellman 3229 parameters, its certificate contains the information required to 3230 complete the key exchange. Note that in this case the client and 3231 server will generate the same Diffie-Hellman result (i.e., 3232 pre_master_secret) every time they communicate. To prevent the 3233 pre_master_secret from staying in memory any longer than necessary, 3234 it should be converted into the master_secret as soon as possible. 3235 Client Diffie-Hellman parameters must be compatible with those 3236 supplied by the server for the key exchange to work. 3238 If the client has a standard DSS or RSA certificate or is 3239 unauthenticated, it sends a set of temporary parameters to the 3240 server in the client key exchange message, then optionally uses a 3241 certificate verify message to authenticate itself. 3243 F.1.2. Version rollback attacks 3245 Because TLS includes substantial improvements over SSL Version 2.0, 3246 attackers may try to make TLS-capable clients and servers fall back 3247 to Version 2.0. This attack can occur if (and only if) two 3248 TLS-capable parties use an SSL 2.0 handshake. 3250 Although the solution using non-random PKCS #1 block type 2 message 3251 padding is inelegant, it provides a reasonably secure way for 3252 Version 3.0 servers to detect the attack. This solution is not 3253 secure against attackers who can brute force the key and substitute 3254 a new ENCRYPTED-KEY-DATA message containing the same key (but with 3255 normal padding) before the application specified wait threshold has 3256 expired. Parties concerned about attacks of this scale should not be 3257 using 40-bit encryption keys anyway. Altering the padding of the 3258 least-significant 8 bytes of the PKCS padding does not impact 3259 security for the size of the signed hashes and RSA key lengths used 3260 in the protocol, since this is essentially equivalent to increasing 3261 the input block size by 8 bytes. 3263 F.1.3. Detecting attacks against the handshake protocol 3265 An attacker might try to influence the handshake exchange to make 3266 the parties select different encryption algorithms than they would 3267 normally choose. Because many implementations will support 40-bit 3268 exportable encryption and some may even support null encryption or 3269 MAC algorithms, this attack is of particular concern. 3271 For this attack, an attacker must actively change one or more 3272 handshake messages. If this occurs, the client and server will 3273 compute different values for the handshake message hashes. As a 3274 result, the parties will not accept each others' finished messages. 3275 Without the master_secret, the attacker cannot repair the finished 3276 messages, so the attack will be discovered. 3278 F.1.4. Resuming sessions 3280 When a connection is established by resuming a session, new 3281 ClientHello.random and ServerHello.random values are hashed with the 3282 session's master_secret. Provided that the master_secret has not 3283 been compromised and that the secure hash operations used to produce 3284 the encryption keys and MAC secrets are secure, the connection 3285 should be secure and effectively independent from previous 3286 connections. Attackers cannot use known encryption keys or MAC 3287 secrets to compromise the master_secret without breaking the secure 3288 hash operations (which use both SHA and MD5). 3290 Sessions cannot be resumed unless both the client and server agree. 3291 If either party suspects that the session may have been compromised, 3292 or that certificates may have expired or been revoked, it should 3293 force a full handshake. An upper limit of 24 hours is suggested for 3294 session ID lifetimes, since an attacker who obtains a master_secret 3295 may be able to impersonate the compromised party until the 3296 corresponding session ID is retired. Applications that may be run in 3297 relatively insecure environments should not write session IDs to 3298 stable storage. 3300 F.1.5. MD5 and SHA 3302 TLS uses hash functions very conservatively. Where possible, both 3303 MD5 and SHA are used in tandem to ensure that non-catastrophic flaws 3304 in one algorithm will not break the overall protocol. 3306 F.2. Protecting application data 3308 The master_secret is hashed with the ClientHello.random and 3309 ServerHello.random to produce unique data encryption keys and MAC 3310 secrets for each connection. 3312 Outgoing data is protected with a MAC before transmission. To 3313 prevent message replay or modification attacks, the MAC is computed 3314 from the MAC secret, the sequence number, the message length, the 3315 message contents, and two fixed character strings. The message type 3316 field is necessary to ensure that messages intended for one TLS 3317 Record Layer client are not redirected to another. The sequence 3318 number ensures that attempts to delete or reorder messages will be 3319 detected. Since sequence numbers are 64-bits long, they should never 3320 overflow. Messages from one party cannot be inserted into the 3321 other's output, since they use independent MAC secrets. Similarly, 3322 the server-write and client-write keys are independent so stream 3323 cipher keys are used only once. 3325 If an attacker does break an encryption key, all messages encrypted 3326 with it can be read. Similarly, compromise of a MAC key can make 3327 message modification attacks possible. Because MACs are also 3328 encrypted, message-alteration attacks generally require breaking the 3329 encryption algorithm as well as the MAC. 3331 Note: MAC secrets may be larger than encryption keys, so messages can 3332 remain tamper resistant even if encryption keys are broken. 3334 F.3. Final notes 3336 For TLS to be able to provide a secure connection, both the client 3337 and server systems, keys, and applications must be secure. In 3338 addition, the implementation must be free of security errors. 3340 The system is only as strong as the weakest key exchange and 3341 authentication algorithm supported, and only trustworthy 3342 cryptographic functions should be used. Short public keys, 40-bit 3343 bulk encryption keys, and anonymous servers should be used with 3344 great caution. Implementations and users must be careful when 3345 deciding which certificates and certificate authorities are 3346 acceptable; a dishonest certificate authority can do tremendous 3347 damage. 3349 Appendix G 3351 G. Patent Statement 3353 Some of the cryptographic algorithms proposed for use in this 3354 protocol have patent claims on them. In addition Netscape 3355 Communications Corporation has a patent claim on the Secure Sockets 3356 Layer (SSL) work that this standard is based on. The Internet 3357 Standards Process as defined in RFC 1310 requires a written 3358 statement from the Patent holder that a license will be made 3359 available to applicants under reasonable terms and conditions prior 3360 to approving a specification as a Proposed, Draft or Internet 3361 Standard. 3363 The Massachusetts Institute of Technology has granted RSA Data 3364 Security, Inc., exclusive sub-licensing rights to the following 3365 patent issued in the United States: 3367 Cryptographic Communications System and Method ("RSA"), No. 3368 4,405,829 3370 Netscape Communications Corporation has been issued the following 3371 patent in the United States: 3373 Secure Socket Layer Application Program Apparatus And Method 3374 ("SSL"), No. 5,657,390 3376 Netscape Communications has issued the following statement: 3378 Intellectual Property Rights 3380 Secure Sockets Layer 3382 The United States Patent and Trademark Office ("the PTO") 3383 recently issued U.S. Patent No. 5,657,390 ("the SSL Patent") to 3384 Netscape for inventions described as Secure Sockets Layers 3385 ("SSL"). The IETF is currently considering adopting SSL as a 3386 transport protocol with security features. Netscape encourages 3387 the royalty-free adoption and use of the SSL protocol upon the 3388 following terms and conditions: 3390 * If you already have a valid SSL Ref license today which 3391 includes source code from Netscape, an additional patent 3392 license under the SSL patent is not required. 3394 * If you don't have an SSL Ref license, you may have a royalty 3395 free license to build implementations covered by the SSL 3396 Patent Claims or the IETF TLS specification provided that 3397 you do not to assert any patent rights against Netscape or 3398 other companies for the implementation of SSL or the IETF 3399 TLS recommendation. 3401 What are "Patent Claims": 3403 Patent claims are claims in an issued foreign or domestic patent 3404 that: 3406 1) must be infringed in order to implement methods or build 3407 products according to the IETF TLS specification; or 3409 2) patent claims which require the elements of the SSL patent 3410 claims and/or their equivalents to be infringed. 3412 The Internet Society, Internet Architecture Board, Internet 3413 Engineering Steering Group and the Corporation for National Research 3414 Initiatives take no position on the validity or scope of the patents 3415 and patent applications, nor on the appropriateness of the terms of 3416 the assurance. The Internet Society and other groups mentioned above 3417 have not made any determination as to any other intellectual 3418 property rights which may apply to the practice of this standard. 3419 Any further consideration of these matters is the user's own 3420 responsibility. 3422 References 3424 [3DES] W. Tuchman, "Hellman Presents No Shortcut Solutions To DES," 3425 IEEE Spectrum, v. 16, n. 7, July 1979, pp40-41. 3427 [DES] ANSI X3.106, "American National Standard for Information 3428 Systems-Data Link Encryption," American National Standards 3429 Institute, 1983. 3431 [DH1] W. Diffie and M. E. Hellman, "New Directions in Cryptography," 3432 IEEE Transactions on Information Theory, V. IT-22, n. 6, Jun 1977, 3433 pp. 74-84. 3435 [DSS] NIST FIPS PUB 186, "Digital Signature Standard," National 3436 Institute of Standards and Technology, U.S. Department of Commerce, 3437 May 18, 1994. 3439 [FTP] J. Postel and J. Reynolds, RFC 959: File Transfer Protocol, 3440 October 1985. 3442 [HTTP] T. Berners-Lee, R. Fielding, H. Frystyk, Hypertext Transfer 3443 Protocol -- HTTP/1.0, October, 1995. 3445 [HMAC] H. Krawczyk, M. Bellare, and R. Canetti, RFC 2104, HMAC: 3446 Keyed-Hashing for Message Authentication, February, 1997. 3448 [IDEA] X. Lai, "On the Design and Security of Block Ciphers," ETH 3449 Series in Information Processing, v. 1, Konstanz: Hartung-Gorre 3450 Verlag, 1992. 3452 [MD2] R. Rivest. RFC 1319: The MD2 Message Digest Algorithm. April 3453 1992. 3455 [MD5] R. Rivest. RFC 1321: The MD5 Message Digest Algorithm. April 3456 1992. 3458 [PKCS1] RSA Laboratories, "PKCS #1: RSA Encryption Standard," 3459 version 1.5, November 1993. 3461 [PKCS6] RSA Laboratories, "PKCS #6: RSA Extended Certificate Syntax 3462 Standard," version 1.5, November 1993. 3464 [PKCS7] RSA Laboratories, "PKCS #7: RSA Cryptographic Message Syntax 3465 Standard," version 1.5, November 1993. 3467 [PKIX] R. Housley, W. Ford, W. Polk, D. Solo, Internet Public Key 3468 Infrastructure: Part I: X.509 Certificate and CRL Profile, 3469 , October 1997. 3471 [RC2] R. Rivest, A Description of the RC2(r) Encryption Algorithm 3472 3474 [RC4] R. Thayer and K. Kaukonen, A Stream Cipher Encryption 3475 Algorithm, , July 1997. 3477 [RSA] R. Rivest, A. Shamir, and L. M. Adleman, "A Method for 3478 Obtaining Digital Signatures and Public-Key Cryptosystems," 3479 Communications of the ACM, v. 21, n. 2, Feb 1978, pp. 120-126. 3481 [RSADSI] Contact RSA Data Security, Inc., Tel: 415-595-8782 [SCH] B. 3482 Schneier. Applied Cryptography: Protocols, Algorithms, and Source 3483 Code in C, Published by John Wiley & Sons, Inc. 1994. 3485 [SHA] NIST FIPS PUB 180-1, "Secure Hash Standard," National 3486 Institute of Standards and Technology, U.S. Department of Commerce, 3487 DRAFT, May 31, 1994. 3489 [SSL2] Hickman, Kipp, "The SSL Protocol", Netscape Communications 3490 Corp., Feb 9, 1995. 3492 [SSL3] A. Frier, P. Karlton, and P. Kocher, "The SSL 3.0 Protocol", 3493 Netscape Communications Corp., Nov 18, 1996. 3495 [TCP] ISI for DARPA, RFC 793: Transport Control Protocol, September 3496 1981. 3498 [TEL] J. Postel and J. Reynolds, RFC 854/5, May, 1993. 3500 [X509] CCITT. Recommendation X.509: "The Directory - Authentication 3501 Framework". 1988. 3503 [XDR] R. Srinivansan, Sun Microsystems, RFC-1832: XDR: External Data 3504 Representation Standard, August 1995. 3506 Credits 3508 Working Group Chair 3510 Win Treese 3511 Open Market 3512 treese@openmarket.com 3514 Editors 3516 Christopher Allen Tim Dierks 3517 Consensus Development Consensus Development 3518 christophera@consensus.com timd@consensus.com 3520 Authors 3522 Tim Dierks Philip L. Karlton 3523 Consensus Development Netscape Communications 3524 timd@consensus.com karlton@netscape.com 3526 Alan O. Freier Paul C. Kocher 3527 Netscape Communications Independent Consultant 3528 freier@netscape.com pck@netcom.com 3530 Other contributors 3532 Martin Abadi Robert Relyea 3533 Digital Equipment Corporation Netscape Communications 3534 ma@pa.dec.com relyea@netscape.com 3536 Ran Canetti Jim Roskind 3537 IBM Watson Research Center Netscape Communications 3538 canetti@watson.ibm.com jar@netscape.com 3540 Taher Elgamal Micheal J. Sabin, Ph. D. 3541 Netscape Communications Consulting Engineer 3542 elgamal@netscape.com msabin@netcom.com 3544 Anil R. Gangolli Dan Simon 3545 Structured Arts Computing Corp. Microsoft 3546 gangolli@structuredarts.com dansimon@microsoft.com 3548 Kipp E.B. Hickman Tom Weinstein 3549 Netscape Communications Netscape Communications 3550 kipp@netscape.com tomw@netscape.com 3552 Hugo Krawczyk 3553 IBM Watson Research Center 3554 hugo@watson.ibm.com 3556 Comments 3558 Comments on this draft should be sent to the editors, Tim Dierks and 3559 Christopher Allen at the address , 3560 or to the IETF Transport Layer Security (TLS) Working Group. 3562 The discussion list for the IETF TLS working group is located at the 3563 e-mail address . Information on the group 3564 and information on how to subscribe to the list is at 3565 . 3567 You can subscribe to the list by sending a message to 3568 with the subject "SUBSCRIBE". You can 3569 subscribe to a digested variant of the list by sending a message to 3570 with the subject "SUBSCRIBE DIGEST". To 3571 remove yourself from the list, send a message to 3572 with the subject "UNSUBSCRIBE". 3574 Archives of the list are at: 3575