idnits 2.17.1 draft-ietf-tls-protocol-06.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-03-19) 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 2285: '...iant application MUST implement the ci...' Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 698 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, 1998) is 9259 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 3107 -- Looks like a reference, but probably isn't: '9' on line 289 -- Looks like a reference, but probably isn't: '2' on line 2428 -- 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 2490 -- Looks like a reference, but probably isn't: '48' on line 2666 -- Looks like a reference, but probably isn't: '32' on line 2668 == Missing Reference: 'ChangeCipherSpec' is mentioned on line 1495, but not defined -- Looks like a reference, but probably isn't: '28' on line 2423 -- Looks like a reference, but probably isn't: '16' on line 2485 -- Looks like a reference, but probably isn't: '46' on line 2519 -- Looks like a reference, but probably isn't: '12' on line 2543 == Unused Reference: 'DH1' is defined on line 3496, but no explicit reference was found in the text == Unused Reference: 'FTP' is defined on line 3504, but no explicit reference was found in the text == Unused Reference: 'HTTP' is defined on line 3507, but no explicit reference was found in the text == Unused Reference: 'MD2' is defined on line 3517, but no explicit reference was found in the text == Unused Reference: 'TEL' is defined on line 3563, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. '3DES' -- Possible downref: Non-RFC (?) normative reference: ref. 'BLEI' -- 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 (==), 37 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 Certicom 3 Expires May 12, 1999 Christopher Allen 4 Certicom 5 November 12, 1998 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 ftp.ietf.org (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 11 56 5. HMAC and the pseudorandom function 11 57 6. The TLS Record Protocol 13 58 6.1. Connection states 13 59 6.2. Record layer 16 60 6.2.1. Fragmentation 16 61 6.2.2. Record compression and decompression 17 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 20 66 6.3.1. Export key generation example 21 67 7. The TLS Handshake Protocol 22 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 30 74 7.4.1. Hello messages 31 75 7.4.1.1. Hello request 31 76 7.4.1.2. Client hello 31 77 7.4.1.3. Server hello 34 78 7.4.2. Server certificate 35 79 7.4.3. Server key exchange message 36 80 7.4.4. Certificate request 39 81 7.4.5. Server hello done 39 82 7.4.6. Client certificate 40 83 7.4.7. Client key exchange message 40 84 7.4.7.1. RSA encrypted premaster secret message 41 85 7.4.7.2. Client Diffie-Hellman public value 42 86 7.4.8. Certificate verify 42 87 7.4.9. Finished 43 88 8. Cryptographic computations 44 89 8.1. Computing the master secret 44 90 8.1.1. RSA 44 91 8.1.2. Diffie-Hellman 45 92 9. Mandatory Cipher Suites 45 93 10. Application data protocol 45 94 A. Protocol constant values 45 95 A.1. Record layer 45 96 A.2. Change cipher specs message 46 97 A.3. Alert messages 46 98 A.4. Handshake protocol 47 99 A.4.1. Hello messages 48 100 A.4.2. Server authentication and key exchange messages 48 101 A.4.3. Client authentication and key exchange messages 49 102 A.4.4. Handshake finalization message 50 103 A.5. The CipherSuite 50 104 A.6. The Security Parameters 52 105 B. Glossary 52 106 C. CipherSuite definitions 56 107 D. Implementation Notes 58 108 D.1. Temporary RSA keys 58 109 D.2. Random Number Generation and Seeding 59 110 D.3. Certificates and authentication 59 111 D.4. CipherSuites 59 112 E. Backward Compatibility With SSL 60 113 E.1. Version 2 client hello 61 114 E.2. Avoiding man-in-the-middle version rollback 62 115 F. Security analysis 62 116 F.1. Handshake protocol 63 117 F.1.1. Authentication and key exchange 63 118 F.1.1.1. Anonymous key exchange 63 119 F.1.1.2. RSA key exchange and authentication 64 120 F.1.1.3. Diffie-Hellman key exchange with authentication 64 121 F.1.2. Version rollback attacks 65 122 F.1.3. Detecting attacks against the handshake protocol 65 123 F.1.4. Resuming sessions 65 124 F.1.5. MD5 and SHA 66 125 F.2. Protecting application data 66 126 F.3. Final notes 66 127 G. Patent Statement 67 128 References 68 129 Credits 71 130 Comments 72 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 6.1). 448 In digital signing, one-way hash functions are used as input for a 449 signing algorithm. A digitally-signed element is encoded as an 450 opaque vector <0..2^16-1>, where the length is specified by the 451 signing algorithm and key. 453 In RSA signing, a 36-byte structure of two hashes (one SHA and one 454 MD5) is signed (encrypted with the private key). It is encoded with 455 PKCS #1 block type 0 or type 1 as described in [PKCS1]. 457 In DSS, the 20 bytes of the SHA hash are run directly through the 458 Digital Signing Algorithm with no additional hashing. This produces 459 two values, r and s. The DSS signature is an opaque vector, as 460 above, the contents of which are the DER encoding of: 462 Dss-Sig-Value ::= SEQUENCE { 463 r INTEGER, 464 s INTEGER 465 } 467 In stream cipher encryption, the plaintext is exclusive-ORed with an 468 identical amount of output generated from a cryptographically-secure 469 keyed pseudorandom number generator. 471 In block cipher encryption, every block of plaintext encrypts to a 472 block of ciphertext. All block cipher encryption is done in CBC 473 (Cipher Block Chaining) mode, and all items which are block-ciphered 474 will be an exact multiple of the cipher block length. 476 In public key encryption, a public key algorithm is used to encrypt 477 data in such a way that it can be decrypted only with the matching 478 private key. A public-key-encrypted element is encoded as an opaque 479 vector <0..2^16-1>, where the length is specified by the signing 480 algorithm and key. 482 An RSA encrypted value is encoded with PKCS #1 block type 2 as 483 described in [PKCS1]. 485 In the following example: 487 stream-ciphered struct { 488 uint8 field1; 489 uint8 field2; 490 digitally-signed opaque hash[20]; 491 } UserType; 493 The contents of hash are used as input for the signing algorithm, 494 then the entire structure is encrypted with a stream cipher. The 495 length of this structure, in bytes would be equal to 2 bytes for 496 field1 and field2, plus two bytes for the length of the signature, 497 plus the length of the output of the signing algorithm. This is 498 known due to the fact that the algorithm and key used for the 499 signing are known prior to encoding or decoding this structure. 501 4.8. Constants 503 Typed constants can be defined for purposes of specification by 504 declaring a symbol of the desired type and assigning values to it. 505 Under-specified types (opaque, variable length vectors, and 506 structures that contain opaque) cannot be assigned values. No fields 507 of a multi-element structure or vector may be elided. 509 For example, 511 struct { 512 uint8 f1; 513 uint8 f2; 514 } Example1; 516 Example1 ex1 = {1, 4}; /* assigns f1 = 1, f2 = 4 */ 518 5. HMAC and the pseudorandom function 520 A number of operations in the TLS record and handshake layer 521 required a keyed MAC; this is a secure digest of some data protected 522 by a secret. Forging the MAC is infeasible without knowledge of the 523 MAC secret. The construction we use for this operation is known as 524 HMAC, described in [HMAC]. 526 HMAC can be used with a variety of different hash algorithms. TLS 527 uses it in the handshake with two different algorithms: MD5 and 528 SHA-1, denoting these as HMAC_MD5(secret, data) and HMAC_SHA(secret, 529 data). Additional hash algorithms can be defined by cipher suites 530 and used to protect record data, but MD5 and SHA-1 are hard coded 531 into the description of the handshaking for this version of the 532 protocol. 534 In addition, a construction is required to do expansion of secrets 535 into blocks of data for the purposes of key generation or 536 validation. This pseudo-random function (PRF) takes as input a 537 secret, a seed, and an identifying label and produces an output of 538 arbitrary length. 540 In order to make the PRF as secure as possible, it uses two hash 541 algorithms in a way which should guarantee its security if either 542 algorithm remains secure. 544 First, we define a data expansion function, P_hash(secret, data) 545 which uses a single hash function to expand a secret and seed into 546 an arbitrary quantity of output: 548 P_hash(secret, seed) = HMAC_hash(secret, A(1) + seed) + 549 HMAC_hash(secret, A(2) + seed) + 550 HMAC_hash(secret, A(3) + seed) + ... 552 Where + indicates concatenation. 554 A() is defined as: 555 A(0) = seed 556 A(i) = HMAC_hash(secret, A(i-1)) 558 P_hash can be iterated as many times as is necessary to produce the 559 required quantity of data. For example, if P_SHA-1 was being used to 560 create 64 bytes of data, it would have to be iterated 4 times 561 (through A(4)), creating 80 bytes of output data; the last 16 bytes 562 of the final iteration would then be discarded, leaving 64 bytes of 563 output data. 565 TLS's PRF is created by splitting the secret into two halves and 566 using one half to generate data with P_MD5 and the other half to 567 generate data with P_SHA-1, then exclusive-or'ing the outputs of 568 these two expansion functions together. 570 S1 and S2 are the two halves of the secret and each is the same 571 length. S1 is taken from the first half of the secret, S2 from the 572 second half. Their length is created by rounding up the length of 573 the overall secret divided by two; thus, if the original secret is 574 an odd number of bytes long, the last byte of S1 will be the same as 575 the first byte of S2. 577 L_S = length in bytes of secret; 578 L_S1 = L_S2 = ceil(L_S / 2); 580 The secret is partitioned into two halves (with the possibility of 581 one shared byte) as described above, S1 taking the first L_S1 bytes 582 and S2 the last L_S2 bytes. 584 The PRF is then defined as the result of mixing the two pseudorandom 585 streams by exclusive-or'ing them together. 587 PRF(secret, label, seed) = P_MD5(S1, label + seed) XOR 588 P_SHA-1(S2, label + seed); 590 The label is an ASCII string. It should be included in the exact 591 form it is given without a length byte or trailing null character. 592 For example, the label "slithy toves" would be processed by hashing 593 the following bytes: 595 73 6C 69 74 68 79 20 74 6F 76 65 73 597 Note that because MD5 produces 16 byte outputs and SHA-1 produces 20 598 byte outputs, the boundaries of their internal iterations will not 599 be aligned; to generate a 80 byte output will involve P_MD5 being 600 iterated through A(5), while P_SHA-1 will only iterate through A(4). 602 6. The TLS Record Protocol 604 The TLS Record Protocol is a layered protocol. At each layer, 605 messages may include fields for length, description, and content. 606 The Record Protocol takes messages to be transmitted, fragments the 607 data into manageable blocks, optionally compresses the data, applies 608 a MAC, encrypts, and transmits the result. Received data is 609 decrypted, verified, decompressed, and reassembled, then delivered 610 to higher level clients. 612 Four record protocol clients are described in this document: the 613 handshake protocol, the alert protocol, the change cipher spec 614 protocol, and the application data protocol. In order to allow 615 extension of the TLS protocol, additional record types can be 616 supported by the record protocol. Any new record types should 617 allocate type values immediately beyond the ContentType values for 618 the four record types described here (see Appendix A.2). If a TLS 619 implementation receives a record type it does not understand, it 620 should just ignore it. Any protocol designed for use over TLS must 621 be carefully designed to deal with all possible attacks against it. 622 Note that because the type and length of a record are not protected 623 by encryption, care should be take to minimize the value of traffic 624 analysis of these values. 626 6.1. Connection states 628 A TLS connection state is the operating environment of the TLS 629 Record Protocol. It specifies a compression algorithm, encryption 630 algorithm, and MAC algorithm. In addition, the parameters for these 631 algorithms are known: the MAC secret and the bulk encryption keys 632 and IVs for the connection in both the read and the write 633 directions. Logically, there are always four connection states 634 outstanding: the current read and write states, and the pending read 635 and write states. All records are processed under the current read 636 and write states. The security parameters for the pending states can 637 be set by the TLS Handshake Protocol, and the Handshake Protocol can 638 selectively make either of the pending states current, in which case 639 the appropriate current state is disposed of and replaced with the 640 pending state; the pending state is then reinitialized to an empty 641 state. It is illegal to make a state which has not been initialized 642 with security parameters a current state. The initial current state 643 always specifies that no encryption, compression, or MAC will be 644 used. 646 The security parameters for a TLS Connection read and write state 647 are set by providing the following values: 649 connection end 650 Whether this entity is considered the "client" or the "server" 651 in this connection. 653 bulk encryption algorithm 654 An algorithm to be used for bulk encryption. This specification 655 includes the key size of this algorithm, how much of that key is 656 secret, whether it is a block or stream cipher, the block size 657 of the cipher (if appropriate), and whether it is considered an 658 "export" cipher. 660 MAC algorithm 661 An algorithm to be used for message authentication. This 662 specification includes the size of the hash which is returned by 663 the MAC algorithm. 665 compression algorithm 666 An algorithm to be used for data compression. This specification 667 must include all information the algorithm requires to do 668 compression. 670 master secret 671 A 48 byte secret shared between the two peers in the connection. 673 client random 674 A 32 byte value provided by the client. 676 server random 677 A 32 byte value provided by the server. 679 These parameters are defined in the presentation language as: 681 enum { server, client } ConnectionEnd; 683 enum { null, rc4, rc2, des, 3des, des40 } BulkCipherAlgorithm; 685 enum { stream, block } CipherType; 687 enum { true, false } IsExportable; 689 enum { null, md5, sha } MACAlgorithm; 691 enum { null(0), (255) } CompressionMethod; 693 /* The algorithms specified in CompressionMethod, 694 BulkCipherAlgorithm, and MACAlgorithm may be added to. */ 696 struct { 697 ConnectionEnd entity; 698 BulkCipherAlgorithm bulk_cipher_algorithm; 699 CipherType cipher_type; 700 uint8 key_size; 701 uint8 key_material_length; 702 IsExportable is_exportable; 703 MACAlgorithm mac_algorithm; 704 uint8 hash_size; 705 CompressionMethod compression_algorithm; 706 opaque master_secret[48]; 707 opaque client_random[32]; 708 opaque server_random[32]; 709 } SecurityParameters; 711 The record layer will use the security parameters to generate the 712 following six items: 714 client write MAC secret 715 server write MAC secret 716 client write key 717 server write key 718 client write IV (for block ciphers only) 719 server write IV (for block ciphers only) 721 The client write parameters are used by the server when receiving 722 and processing records and vice-versa. The algorithm used for 723 generating these items from the security parameters is described in 724 section 6.3. 726 Once the security parameters have been set and the keys have been 727 generated, the connection states can be instantiated by making them 728 the current states. These current states must be updated for each 729 record processed. Each connection state includes the following 730 elements: 732 compression state 733 The current state of the compression algorithm. 735 cipher state 736 The current state of the encryption algorithm. This will consist 737 of the scheduled key for that connection. In addition, for block 738 ciphers running in CBC mode (the only mode specified for TLS), 739 this will initially contain the IV for that connection state and 740 be updated to contain the ciphertext of the last block encrypted 741 or decrypted as records are processed. For stream ciphers, this 742 will contain whatever the necessary state information is to 743 allow the stream to continue to encrypt or decrypt data. 745 MAC secret 746 The MAC secret for this connection as generated above. 748 sequence number 749 Each connection state contains a sequence number, which is 750 maintained separately for read and write states. The sequence 751 number must be set to zero whenever a connection state is made 752 the active state. Sequence numbers are of type uint64 and may 753 not exceed 2^64-1. A sequence number is incremented after each 754 record: specifically, the first record which is transmitted 755 under a particular connection state should use sequence number 756 0. 758 6.2. Record layer 760 The TLS Record Layer receives uninterpreted data from higher layers 761 in non-empty blocks of arbitrary size. 763 6.2.1. Fragmentation 765 The record layer fragments information blocks into TLSPlaintext 766 records carrying data in chunks of 2^14 bytes or less. Client 767 message boundaries are not preserved in the record layer (i.e., 768 multiple client messages of the same ContentType may be coalesced 769 into a single TLSPlaintext record, or a single message may be 770 fragmented across several records). 772 struct { 773 uint8 major, minor; 774 } ProtocolVersion; 776 enum { 777 change_cipher_spec(20), alert(21), handshake(22), 778 application_data(23), (255) 779 } ContentType; 781 struct { 782 ContentType type; 783 ProtocolVersion version; 784 uint16 length; 785 opaque fragment[TLSPlaintext.length]; 786 } TLSPlaintext; 788 type 789 The higher level protocol used to process the enclosed fragment. 791 version 792 The version of the protocol being employed. This document 793 describes TLS Version 1.0, which uses the version { 3, 1 }. The 794 version value 3.1 is historical: TLS version 1.0 is a minor 795 modification to the SSL 3.0 protocol, which bears the version 796 value 3.0. (See Appendix A.1). 798 length 799 The length (in bytes) of the following TLSPlaintext.fragment. 800 The length should not exceed 2^14. 802 fragment 803 The application data. This data is transparent and treated as an 804 independent block to be dealt with by the higher level protocol 805 specified by the type field. 807 Note: Data of different TLS Record layer content types may be 808 interleaved. Application data is generally of lower precedence 809 for transmission than other content types. 811 6.2.2. Record compression and decompression 813 All records are compressed using the compression algorithm defined 814 in the current session state. There is always an active compression 815 algorithm; however, initially it is defined as 816 CompressionMethod.null. The compression algorithm translates a 817 TLSPlaintext structure into a TLSCompressed structure. Compression 818 functions are initialized with default state information whenever a 819 connection state is made active. 821 Compression must be lossless and may not increase the content length 822 by more than 1024 bytes. If the decompression function encounters a 823 TLSCompressed.fragment that would decompress to a length in excess 824 of 2^14 bytes, it should report a fatal decompression failure error. 826 struct { 827 ContentType type; /* same as TLSPlaintext.type */ 828 ProtocolVersion version;/* same as TLSPlaintext.version */ 829 uint16 length; 830 opaque fragment[TLSCompressed.length]; 831 } TLSCompressed; 833 length 834 The length (in bytes) of the following TLSCompressed.fragment. 835 The length should not exceed 2^14 + 1024. 837 fragment 838 The compressed form of TLSPlaintext.fragment. 840 Note: A CompressionMethod.null operation is an identity operation; no 841 fields are altered. 843 Implementation note: 844 Decompression functions are responsible for ensuring that 845 messages cannot cause internal buffer overflows. 847 6.2.3. Record payload protection 849 The encryption and MAC functions translate a TLSCompressed structure 850 into a TLSCiphertext. The decryption functions reverse the process. 851 The MAC of the record also includes a sequence number so that 852 missing, extra or repeated messages are detectable. 854 struct { 855 ContentType type; 856 ProtocolVersion version; 857 uint16 length; 858 select (CipherSpec.cipher_type) { 859 case stream: GenericStreamCipher; 860 case block: GenericBlockCipher; 861 } fragment; 862 } TLSCiphertext; 864 type 865 The type field is identical to TLSCompressed.type. 867 version 868 The version field is identical to TLSCompressed.version. 870 length 871 The length (in bytes) of the following TLSCiphertext.fragment. 872 The length may not exceed 2^14 + 2048. 874 fragment 875 The encrypted form of TLSCompressed.fragment, with the MAC. 877 6.2.3.1. Null or standard stream cipher 879 Stream ciphers (including BulkCipherAlgorithm.null - see Appendix 880 A.6) convert TLSCompressed.fragment structures to and from stream 881 TLSCiphertext.fragment structures. 883 stream-ciphered struct { 884 opaque content[TLSCompressed.length]; 885 opaque MAC[CipherSpec.hash_size]; 886 } GenericStreamCipher; 888 The MAC is generated as: 890 HMAC_hash(MAC_write_secret, seq_num + TLSCompressed.type + 891 TLSCompressed.version + TLSCompressed.length + 892 TLSCompressed.fragment)); 894 where "+" denotes concatenation. 896 seq_num 897 The sequence number for this record. 899 hash 900 The hashing algorithm specified by 901 SecurityParameters.mac_algorithm. 903 Note that the MAC is computed before encryption. The stream cipher 904 encrypts the entire block, including the MAC. For stream ciphers 905 that do not use a synchronization vector (such as RC4), the stream 906 cipher state from the end of one record is simply used on the 907 subsequent packet. If the CipherSuite is TLS_NULL_WITH_NULL_NULL, 908 encryption consists of the identity operation (i.e., the data is not 909 encrypted and the MAC size is zero implying that no MAC is used). 910 TLSCiphertext.length is TLSCompressed.length plus 911 CipherSpec.hash_size. 913 6.2.3.2. CBC block cipher 915 For block ciphers (such as RC2 or DES), the encryption and MAC 916 functions convert TLSCompressed.fragment structures to and from 917 block TLSCiphertext.fragment structures. 919 block-ciphered struct { 920 opaque content[TLSCompressed.length]; 921 opaque MAC[CipherSpec.hash_size]; 922 uint8 padding[GenericBlockCipher.padding_length]; 923 uint8 padding_length; 924 } GenericBlockCipher; 926 The MAC is generated as described in Section 6.2.3.1. 928 padding 929 Padding that is added to force the length of the plaintext to be 930 an integral multiple of the block cipher's block length. The 931 padding may be any length up to 255 bytes long, as long as it 932 results in the TLSCiphertext.length being an integral multiple 933 of the block length. Lengths longer than necessary might be 934 desirable to frustrate attacks on a protocol based on analysis 935 of the lengths of exchanged messages. Each uint8 in the padding 936 data vector must be filled with the padding length value. 938 padding_length 939 The padding length should be such that the total size of the 940 GenericBlockCipher structure is a multiple of the cipher's block 941 length. Legal values range from zero to 255, inclusive. This 942 length specifies the length of the padding field exclusive of 943 the padding_length field itself. 945 The encrypted data length (TLSCiphertext.length) is one more than 946 the sum of TLSCompressed.length, CipherSpec.hash_size, and 947 padding_length. 949 Example: If the block length is 8 bytes, the content length 950 (TLSCompressed.length) is 61 bytes, and the MAC length is 20 951 bytes, the length before padding is 82 bytes. Thus, the 952 padding length modulo 8 must be equal to 6 in order to make 953 the total length an even multiple of 8 bytes (the block 954 length). The padding length can be 6, 14, 22, and so on, 955 through 254. If the padding length were the minimum necessary, 956 6, the padding would be 6 bytes, each containing the value 6. 957 Thus, the last 8 octets of the GenericBlockCipher before block 958 encryption would be xx 06 06 06 06 06 06 06, where xx is the 959 last octet of the MAC. 961 Note: With block ciphers in CBC mode (Cipher Block Chaining) the 962 initialization vector (IV) for the first record is generated 963 with the other keys and secrets when the security parameters are 964 set. The IV for subsequent records is the last ciphertext block 965 from the previous record. 967 6.3. Key calculation 969 The Record Protocol requires an algorithm to generate keys, IVs, and 970 MAC secrets from the security parameters provided by the handshake 971 protocol. 973 The master secret is hashed into a sequence of secure bytes, which 974 are assigned to the MAC secrets, keys, and non-export IVs required 975 by the current connection state (see Appendix A.6). CipherSpecs 976 require a client write MAC secret, a server write MAC secret, a 977 client write key, a server write key, a client write IV, and a 978 server write IV, which are generated from the master secret in that 979 order. Unused values are empty. 981 When generating keys and MAC secrets, the master secret is used as 982 an entropy source, and the random values provide unencrypted salt 983 material and IVs for exportable ciphers. 985 To generate the key material, compute 987 key_block = PRF(SecurityParameters.master_secret, 988 "key expansion", 989 SecurityParameters.server_random + 990 SecurityParameters.client_random); 992 until enough output has been generated. Then the key_block is 993 partitioned as follows: 995 client_write_MAC_secret[SecurityParameters.hash_size] 996 server_write_MAC_secret[SecurityParameters.hash_size] 997 client_write_key[SecurityParameters.key_material] 998 server_write_key[SecurityParameters.key_material] 999 client_write_IV[SecurityParameters.IV_size] 1000 server_write_IV[SecurityParameters.IV_size] 1002 The client_write_IV and server_write_IV are only generated for 1003 non-export block ciphers. For exportable block ciphers, the 1004 initialization vectors are generated later, as described below. Any 1005 extra key_block material is discarded. 1007 Implementation note: 1008 The cipher spec which is defined in this document which requires 1009 the most material is 3DES_EDE_CBC_SHA: it requires 2 x 24 byte 1010 keys, 2 x 20 byte MAC secrets, and 2 x 8 byte IVs, for a total 1011 of 104 bytes of key material. 1013 Exportable encryption algorithms (for which CipherSpec.is_exportable 1014 is true) require additional processing as follows to derive their 1015 final write keys: 1017 final_client_write_key = 1018 PRF(SecurityParameters.client_write_key, 1019 "client write key", 1020 SecurityParameters.client_random + 1021 SecurityParameters.server_random); 1022 final_server_write_key = 1023 PRF(SecurityParameters.server_write_key, 1024 "server write key", 1025 SecurityParameters.client_random + 1026 SecurityParameters.server_random); 1028 Exportable encryption algorithms derive their IVs solely from the 1029 random values from the hello messages: 1031 iv_block = PRF("", "IV block", SecurityParameters.client_random 1032 + 1033 SecurityParameters.server_random); 1035 The iv_block is partitioned into two initialization vectors as the 1036 key_block was above: 1038 client_write_IV[SecurityParameters.IV_size] 1039 server_write_IV[SecurityParameters.IV_size] 1041 Note that the PRF is used without a secret in this case: this just 1042 means that the secret has a length of zero bytes and contributes 1043 nothing to the hashing in the PRF. 1045 6.3.1. Export key generation example 1047 TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 requires five random bytes for 1048 each of the two encryption keys and 16 bytes for each of the MAC 1049 keys, for a total of 42 bytes of key material. The PRF output is 1050 stored in the key_block. The key_block is partitioned, and the write 1051 keys are salted because this is an exportable encryption algorithm. 1053 key_block = PRF(master_secret, 1054 "key expansion", 1055 server_random + 1056 client_random)[0..41] 1057 client_write_MAC_secret = key_block[0..15] 1058 server_write_MAC_secret = key_block[16..31] 1059 client_write_key = key_block[32..36] 1060 server_write_key = key_block[37..41] 1061 final_client_write_key = PRF(client_write_key, 1062 "client write key", 1063 client_random + 1064 server_random)[0..15] 1065 final_server_write_key = PRF(server_write_key, 1066 "server write key", 1067 client_random + 1068 server_random)[0..15] 1070 iv_block = PRF("", "IV block", client_random + 1071 server_random)[0..15] 1072 client_write_IV = iv_block[0..7] 1073 server_write_IV = iv_block[8..15] 1075 7. The TLS Handshake Protocol 1077 The TLS Handshake Protocol consists of a suite of three 1078 sub-protocols which are used to allow peers to agree upon security 1079 parameters for the record layer, authenticate themselves, 1080 instantiate negotiated security parameters, and report error 1081 conditions to each other. 1083 The Handshake Protocol is responsible for negotiating a session, 1084 which consists of the following items: 1086 session identifier 1087 An arbitrary byte sequence chosen by the server to identify an 1088 active or resumable session state. 1090 peer certificate 1091 X509v3[X509] certificate of the peer. This element of the state 1092 may be null. 1094 compression method 1095 The algorithm used to compress data prior to encryption. 1097 cipher spec 1098 Specifies the bulk data encryption algorithm (such as null, DES, 1099 etc.) and a MAC algorithm (such as MD5 or SHA). It also defines 1100 cryptographic attributes such as the hash_size. (See Appendix 1101 A.6 for formal definition) 1103 master secret 1104 48-byte secret shared between the client and server. 1106 is resumable 1107 A flag indicating whether the session can be used to initiate 1108 new connections. 1110 These items are then used to create security parameters for use by 1111 the Record Layer when protecting application data. Many connections 1112 can be instantiated using the same session through the resumption 1113 feature of the TLS Handshake Protocol. 1115 7.1. Change cipher spec protocol 1117 The change cipher spec protocol exists to signal transitions in 1118 ciphering strategies. The protocol consists of a single message, 1119 which is encrypted and compressed under the current (not the 1120 pending) connection state. The message consists of a single byte of 1121 value 1. 1123 struct { 1124 enum { change_cipher_spec(1), (255) } type; 1125 } ChangeCipherSpec; 1127 The change cipher spec message is sent by both the client and server 1128 to notify the receiving party that subsequent records will be 1129 protected under the newly negotiated CipherSpec and keys. Reception 1130 of this message causes the receiver to instruct the Record Layer to 1131 immediately copy the read pending state into the read current state. 1132 Immediately after sending this message, the sender should instruct 1133 the record layer to make the write pending state the write active 1134 state. (See section 6.1.) The change cipher spec message is sent 1135 during the handshake after the security parameters have been agreed 1136 upon, but before the verifying finished message is sent (see section 1137 7.4.9). 1139 7.2. Alert protocol 1141 One of the content types supported by the TLS Record layer is the 1142 alert type. Alert messages convey the severity of the message and a 1143 description of the alert. Alert messages with a level of fatal 1144 result in the immediate termination of the connection. In this case, 1145 other connections corresponding to the session may continue, but the 1146 session identifier must be invalidated, preventing the failed 1147 session from being used to establish new connections. Like other 1148 messages, alert messages are encrypted and compressed, as specified 1149 by the current connection state. 1151 enum { warning(1), fatal(2), (255) } AlertLevel; 1153 enum { 1154 close_notify(0), 1155 unexpected_message(10), 1156 bad_record_mac(20), 1157 decryption_failed(21), 1158 record_overflow(22), 1159 decompression_failure(30), 1160 handshake_failure(40), 1161 bad_certificate(42), 1162 unsupported_certificate(43), 1163 certificate_revoked(44), 1164 certificate_expired(45), 1165 certificate_unknown(46), 1166 illegal_parameter(47), 1167 unknown_ca(48), 1168 access_denied(49), 1169 decode_error(50), 1170 decrypt_error(51), 1171 export_restriction(60), 1172 protocol_version(70), 1173 insufficient_security(71), 1174 internal_error(80), 1175 user_canceled(90), 1176 no_renegotiation(100), 1177 (255) 1178 } AlertDescription; 1180 struct { 1181 AlertLevel level; 1182 AlertDescription description; 1183 } Alert; 1185 7.2.1. Closure alerts 1187 The client and the server must share knowledge that the connection 1188 is ending in order to avoid a truncation attack. Either party may 1189 initiate the exchange of closing messages. 1191 close_notify 1192 This message notifies the recipient that the sender will not 1193 send any more messages on this connection. The session becomes 1194 unresumable if any connection is terminated without proper 1195 close_notify messages with level equal to warning. 1197 Either party may initiate a close by sending a close_notify alert. 1198 Any data received after a closure alert is ignored. 1200 Each party is required to send a close_notify alert before closing 1201 the write side of the connection. It is required that the other 1202 party respond with a close_notify alert of its own and close down 1203 the connection immediately, discarding any pending writes. It is not 1204 required for the initiator of the close to wait for the responding 1205 close_notify alert before closing the read side of the connection. 1207 If the application protocol using TLS provides that any data may be 1208 carried over the underlying transport after the TLS connection is 1209 closed, the TLS implementation must receive the responding 1210 close_notify alert before indicating to the application layer that 1211 the TLS connection has ended. If the application protocol will not 1212 transfer any additional data, but will only close the underlying 1213 transport connection, then the implementation may choose to close 1214 the transport without waiting for the responding close_notify. No 1215 part of this standard should be taken to dictate the manner in which 1216 a usage profile for TLS manages its data transport, including when 1217 connections are opened or closed. 1219 NB: It is assumed that closing a connection reliably delivers 1220 pending data before destroying the transport. 1222 7.2.2. Error alerts 1224 Error handling in the TLS Handshake protocol is very simple. When an 1225 error is detected, the detecting party sends a message to the other 1226 party. Upon transmission or receipt of an fatal alert message, both 1227 parties immediately close the connection. Servers and clients are 1228 required to forget any session-identifiers, keys, and secrets 1229 associated with a failed connection. The following error alerts are 1230 defined: 1232 unexpected_message 1233 An inappropriate message was received. This alert is always 1234 fatal and should never be observed in communication between 1235 proper implementations. 1237 bad_record_mac 1238 This alert is returned if a record is received with an incorrect 1239 MAC. This message is always fatal. 1241 decryption_failed 1242 A TLSCiphertext decrypted in an invalid way: either it wasn`t an 1243 even multiple of the block length or its padding values, when 1244 checked, weren`t correct. This message is always fatal. 1246 record_overflow 1247 A TLSCiphertext record was received which had a length more than 1248 2^14+2048 bytes, or a record decrypted to a TLSCompressed record 1249 with more than 2^14+1024 bytes. This message is always fatal. 1251 decompression_failure 1252 The decompression function received improper input (e.g. data 1253 that would expand to excessive length). This message is always 1254 fatal. 1256 handshake_failure 1257 Reception of a handshake_failure alert message indicates that 1258 the sender was unable to negotiate an acceptable set of security 1259 parameters given the options available. This is a fatal error. 1261 bad_certificate 1262 A certificate was corrupt, contained signatures that did not 1263 verify correctly, etc. 1265 unsupported_certificate 1266 A certificate was of an unsupported type. 1268 certificate_revoked 1269 A certificate was revoked by its signer. 1271 certificate_expired 1272 A certificate has expired or is not currently valid. 1274 certificate_unknown 1275 Some other (unspecified) issue arose in processing the 1276 certificate, rendering it unacceptable. 1278 illegal_parameter 1279 A field in the handshake was out of range or inconsistent with 1280 other fields. This is always fatal. 1282 unknown_ca 1283 A valid certificate chain or partial chain was received, but the 1284 certificate was not accepted because the CA certificate could 1285 not be located or couldn`t be matched with a known, trusted CA. 1286 This message is always fatal. 1288 access_denied 1289 A valid certificate was received, but when access control was 1290 applied, the sender decided not to proceed with negotiation. 1291 This message is always fatal. 1293 decode_error 1294 A message could not be decoded because some field was out of the 1295 specified range or the length of the message was incorrect. This 1296 message is always fatal. 1298 decrypt_error 1299 A handshake cryptographic operation failed, including being 1300 unable to correctly verify a signature, decrypt a key exchange, 1301 or validate a finished message. 1303 export_restriction 1304 A negotiation not in compliance with export restrictions was 1305 detected; for example, attempting to transfer a 1024 bit 1306 ephemeral RSA key for the RSA_EXPORT handshake method. This 1307 message is always fatal. 1309 protocol_version 1310 The protocol version the client has attempted to negotiate is 1311 recognized, but not supported. (For example, old protocol 1312 versions might be avoided for security reasons). This message is 1313 always fatal. 1315 insufficient_security 1316 Returned instead of handshake_failure when a negotiation has 1317 failed specifically because the server requires ciphers more 1318 secure than those supported by the client. This message is 1319 always fatal. 1321 internal_error 1322 An internal error unrelated to the peer or the correctness of 1323 the protocol makes it impossible to continue (such as a memory 1324 allocation failure). This message is always fatal. 1326 user_canceled 1327 This handshake is being canceled for some reason unrelated to a 1328 protocol failure. If the user cancels an operation after the 1329 handshake is complete, just closing the connection by sending a 1330 close_notify is more appropriate. This alert should be followed 1331 by a close_notify. This message is generally a warning. 1333 no_renegotiation 1334 Sent by the client in response to a hello request or by the 1335 server in response to a client hello after initial handshaking. 1336 Either of these would normally lead to renegotiation; when that 1337 is not appropriate, the recipient should respond with this 1338 alert; at that point, the original requester can decide whether 1339 to proceed with the connection. One case where this would be 1340 appropriate would be where a server has spawned a process to 1341 satisfy a request; the process might receive security parameters 1342 (key length, authentication, etc.) at startup and it might be 1343 difficult to communicate changes to these parameters after that 1344 point. This message is always a warning. 1346 For all errors where an alert level is not explicitly specified, the 1347 sending party may determine at its discretion whether this is a 1348 fatal error or not; if an alert with a level of warning is received, 1349 the receiving party may decide at its discretion whether to treat 1350 this as a fatal error or not. However, all messages which are 1351 transmitted with a level of fatal must be treated as fatal messages. 1353 7.3. Handshake Protocol overview 1355 The cryptographic parameters of the session state are produced by 1356 the TLS Handshake Protocol, which operates on top of the TLS Record 1357 Layer. When a TLS client and server first start communicating, they 1358 agree on a protocol version, select cryptographic algorithms, 1359 optionally authenticate each other, and use public-key encryption 1360 techniques to generate shared secrets. 1362 The TLS Handshake Protocol involves the following steps: 1364 - Exchange hello messages to agree on algorithms, exchange random 1365 values, and check for session resumption. 1367 - Exchange the necessary cryptographic parameters to allow the 1368 client and server to agree on a premaster secret. 1370 - Exchange certificates and cryptographic information to allow the 1371 client and server to authenticate themselves. 1373 - Generate a master secret from the premaster secret and exchanged 1374 random values. 1376 - Provide security parameters to the record layer. 1378 - Allow the client and server to verify that their peer has 1379 calculated the same security parameters and that the handshake 1380 occurred without tampering by an attacker. 1382 Note that higher layers should not be overly reliant on TLS always 1383 negotiating the strongest possible connection between two peers: 1384 there are a number of ways a man in the middle attacker can attempt 1385 to make two entities drop down to the least secure method they 1386 support. The protocol has been designed to minimize this risk, but 1387 there are still attacks available: for example, an attacker could 1388 block access to the port a secure service runs on, or attempt to get 1389 the peers to negotiate an unauthenticated connection. The 1390 fundamental rule is that higher levels must be cognizant of what 1391 their security requirements are and never transmit information over 1392 a channel less secure than what they require. The TLS protocol is 1393 secure, in that any cipher suite offers its promised level of 1394 security: if you negotiate 3DES with a 1024 bit RSA key exchange 1395 with a host whose certificate you have verified, you can expect to 1396 be that secure. However, you should never send data over a link 1397 encrypted with 40 bit security unless you feel that data is worth no 1398 more than the effort required to break that encryption. 1400 These goals are achieved by the handshake protocol, which can be 1401 summarized as follows: The client sends a client hello message to 1402 which the server must respond with a server hello message, or else a 1403 fatal error will occur and the connection will fail. The client 1404 hello and server hello are used to establish security enhancement 1405 capabilities between client and server. The client hello and server 1406 hello establish the following attributes: Protocol Version, Session 1407 ID, Cipher Suite, and Compression Method. Additionally, two random 1408 values are generated and exchanged: ClientHello.random and 1409 ServerHello.random. 1411 The actual key exchange uses up to four messages: the server 1412 certificate, the server key exchange, the client certificate, and 1413 the client key exchange. New key exchange methods can be created by 1414 specifying a format for these messages and defining the use of the 1415 messages to allow the client and server to agree upon a shared 1416 secret. This secret should be quite long; currently defined key 1417 exchange methods exchange secrets which range from 48 to 128 bytes 1418 in length. 1420 Following the hello messages, the server will send its certificate, 1421 if it is to be authenticated. Additionally, a server key exchange 1422 message may be sent, if it is required (e.g. if their server has no 1423 certificate, or if its certificate is for signing only). If the 1424 server is authenticated, it may request a certificate from the 1425 client, if that is appropriate to the cipher suite selected. Now the 1426 server will send the server hello done message, indicating that the 1427 hello-message phase of the handshake is complete. The server will 1428 then wait for a client response. If the server has sent a 1429 certificate request message, the client must send the certificate 1430 message. The client key exchange message is now sent, and the 1431 content of that message will depend on the public key algorithm 1432 selected between the client hello and the server hello. If the 1433 client has sent a certificate with signing ability, a 1434 digitally-signed certificate verify message is sent to explicitly 1435 verify the certificate. 1437 At this point, a change cipher spec message is sent by the client, 1438 and the client copies the pending Cipher Spec into the current 1439 Cipher Spec. The client then immediately sends the finished message 1440 under the new algorithms, keys, and secrets. In response, the server 1441 will send its own change cipher spec message, transfer the pending 1442 to the current Cipher Spec, and send its finished message under the 1443 new Cipher Spec. At this point, the handshake is complete and the 1444 client and server may begin to exchange application layer data. (See 1445 flow chart below.) 1447 Client Server 1449 ClientHello --------> 1450 ServerHello 1451 Certificate* 1452 ServerKeyExchange* 1453 CertificateRequest* 1454 <-------- ServerHelloDone 1455 Certificate* 1456 ClientKeyExchange 1457 CertificateVerify* 1458 [ChangeCipherSpec] 1459 Finished --------> 1460 [ChangeCipherSpec] 1461 <-------- Finished 1462 Application Data <-------> Application Data 1464 Fig. 1 - Message flow for a full handshake 1466 * Indicates optional or situation-dependent messages that are not 1467 always sent. 1469 Note: To help avoid pipeline stalls, ChangeCipherSpec is an 1470 independent TLS Protocol content type, and is not actually a TLS 1471 handshake message. 1473 When the client and server decide to resume a previous session or 1474 duplicate an existing session (instead of negotiating new security 1475 parameters) the message flow is as follows: 1477 The client sends a ClientHello using the Session ID of the session 1478 to be resumed. The server then checks its session cache for a match. 1479 If a match is found, and the server is willing to re-establish the 1480 connection under the specified session state, it will send a 1481 ServerHello with the same Session ID value. At this point, both 1482 client and server must send change cipher spec messages and proceed 1483 directly to finished messages. Once the re-establishment is 1484 complete, the client and server may begin to exchange application 1485 layer data. (See flow chart below.) If a Session ID match is not 1486 found, the server generates a new session ID and the TLS client and 1487 server perform a full handshake. 1489 Client Server 1491 ClientHello --------> 1492 ServerHello 1493 [ChangeCipherSpec] 1494 <-------- Finished 1495 [ChangeCipherSpec] 1496 Finished --------> 1497 Application Data <-------> Application Data 1499 Fig. 2 - Message flow for an abbreviated handshake 1501 The contents and significance of each message will be presented in 1502 detail in the following sections. 1504 7.4. Handshake protocol 1506 The TLS Handshake Protocol is one of the defined higher level 1507 clients of the TLS Record Protocol. This protocol is used to 1508 negotiate the secure attributes of a session. Handshake messages are 1509 supplied to the TLS Record Layer, where they are encapsulated within 1510 one or more TLSPlaintext structures, which are processed and 1511 transmitted as specified by the current active session state. 1513 enum { 1514 hello_request(0), client_hello(1), server_hello(2), 1515 certificate(11), server_key_exchange (12), 1516 certificate_request(13), server_hello_done(14), 1517 certificate_verify(15), client_key_exchange(16), 1518 finished(20), (255) 1519 } HandshakeType; 1521 struct { 1522 HandshakeType msg_type; /* handshake type */ 1523 uint24 length; /* bytes in message */ 1524 select (HandshakeType) { 1525 case hello_request: HelloRequest; 1526 case client_hello: ClientHello; 1527 case server_hello: ServerHello; 1528 case certificate: Certificate; 1529 case server_key_exchange: ServerKeyExchange; 1530 case certificate_request: CertificateRequest; 1531 case server_hello_done: ServerHelloDone; 1532 case certificate_verify: CertificateVerify; 1533 case client_key_exchange: ClientKeyExchange; 1534 case finished: Finished; 1535 } body; 1536 } Handshake; 1538 The handshake protocol messages are presented below in the order 1539 they must be sent; sending handshake messages in an unexpected order 1540 results in a fatal error. Unneeded handshake messages can be 1541 omitted, however. Note one exception to the ordering: the 1542 Certificate message is used twice in the handshake (from server to 1543 client, then from client to server), but described only in its first 1544 position. The one message which is not bound by these ordering rules 1545 in the Hello Request message, which can be sent at any time, but 1546 which should be ignored by the client if it arrives in the middle of 1547 a handshake. 1549 7.4.1. Hello messages 1551 The hello phase messages are used to exchange security enhancement 1552 capabilities between the client and server. When a new session 1553 begins, the Record Layer's connection state encryption, hash, and 1554 compression algorithms are initialized to null. The current 1555 connection state is used for renegotiation messages. 1557 7.4.1.1. Hello request 1559 When this message will be sent: 1560 The hello request message may be sent by the server at any time. 1562 Meaning of this message: 1563 Hello request is a simple notification that the client should 1564 begin the negotiation process anew by sending a client hello 1565 message when convenient. This message will be ignored by the 1566 client if the client is currently negotiating a session. This 1567 message may be ignored by the client if it does not wish to 1568 renegotiate a session, or the client may, if it wishes, respond 1569 with a no_renegotiation alert. Since handshake messages are 1570 intended to have transmission precedence over application data, 1571 it is expected that the negotiation will begin before no more 1572 than a few records are received from the client. If the server 1573 sends a hello request but does not receive a client hello in 1574 response, it may close the connection with a fatal alert. 1576 After sending a hello request, servers should not repeat the request 1577 until the subsequent handshake negotiation is complete. 1579 Structure of this message: 1580 struct { } HelloRequest; 1582 Note: This message should never be included in the message hashes 1583 which are maintained throughout the handshake and used in the 1584 finished messages and the certificate verify message. 1586 7.4.1.2. Client hello 1588 When this message will be sent: 1589 When a client first connects to a server it is required to send 1590 the client hello as its first message. The client can also send 1591 a client hello in response to a hello request or on its own 1592 initiative in order to renegotiate the security parameters in an 1593 existing connection. 1595 Structure of this message: 1596 The client hello message includes a random structure, which is 1597 used later in the protocol. 1599 struct { 1600 uint32 gmt_unix_time; 1601 opaque random_bytes[28]; 1602 } Random; 1604 gmt_unix_time 1605 The current time and date in standard UNIX 32-bit format 1606 (seconds since the midnight starting Jan 1, 1970, GMT) according 1607 to the sender's internal clock. Clocks are not required to be 1608 set correctly by the basic TLS Protocol; higher level or 1609 application protocols may define additional requirements. 1611 random_bytes 1612 28 bytes generated by a secure random number generator. 1614 The client hello message includes a variable length session 1615 identifier. If not empty, the value identifies a session between the 1616 same client and server whose security parameters the client wishes 1617 to reuse. The session identifier may be from an earlier connection, 1618 this connection, or another currently active connection. The second 1619 option is useful if the client only wishes to update the random 1620 structures and derived values of a connection, while the third 1621 option makes it possible to establish several independent secure 1622 connections without repeating the full handshake protocol. These 1623 independent connections may occur sequentially or simultaneously; a 1624 SessionID becomes valid when the handshake negotiating it completes 1625 with the exchange of Finished messages and persists until removed 1626 due to aging or because a fatal error was encountered on a 1627 connection associated with the session. The actual contents of the 1628 SessionID are defined by the server. 1630 opaque SessionID<0..32>; 1632 Warning: 1633 Because the SessionID is transmitted without encryption or 1634 immediate MAC protection, servers must not place confidential 1635 information in session identifiers or let the contents of fake 1636 session identifiers cause any breach of security. (Note that the 1637 content of the handshake as a whole, including the SessionID, is 1638 protected by the Finished messages exchanged at the end of the 1639 handshake.) 1641 The CipherSuite list, passed from the client to the server in the 1642 client hello message, contains the combinations of cryptographic 1643 algorithms supported by the client in order of the client's 1644 preference (favorite choice first). Each CipherSuite defines a key 1645 exchange algorithm, a bulk encryption algorithm (including secret 1646 key length) and a MAC algorithm. The server will select a cipher 1647 suite or, if no acceptable choices are presented, return a handshake 1648 failure alert and close the connection. 1650 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 1652 The client hello includes a list of compression algorithms supported 1653 by the client, ordered according to the client's preference. 1655 enum { null(0), (255) } CompressionMethod; 1657 struct { 1658 ProtocolVersion client_version; 1659 Random random; 1660 SessionID session_id; 1661 CipherSuite cipher_suites<2..2^16-1>; 1662 CompressionMethod compression_methods<1..2^8-1>; 1663 } ClientHello; 1665 client_version 1666 The version of the TLS protocol by which the client wishes to 1667 communicate during this session. This should be the latest 1668 (highest valued) version supported by the client. For this 1669 version of the specification, the version will be 3.1 (See 1670 Appendix E for details about backward compatibility). 1672 random 1673 A client-generated random structure. 1675 session_id 1676 The ID of a session the client wishes to use for this 1677 connection. This field should be empty if no session_id is 1678 available or the client wishes to generate new security 1679 parameters. 1681 cipher_suites 1682 This is a list of the cryptographic options supported by the 1683 client, with the client's first preference first. If the 1684 session_id field is not empty (implying a session resumption 1685 request) this vector must include at least the cipher_suite from 1686 that session. Values are defined in Appendix A.5. 1688 compression_methods 1689 This is a list of the compression methods supported by the 1690 client, sorted by client preference. If the session_id field is 1691 not empty (implying a session resumption request) it must 1692 include the compression_method from that session. This vector 1693 must contain, and all implementations must support, 1694 CompressionMethod.null. Thus, a client and server will always be 1695 able to agree on a compression method. 1697 After sending the client hello message, the client waits for a 1698 server hello message. Any other handshake message returned by the 1699 server except for a hello request is treated as a fatal error. 1701 Forward compatibility note: 1702 In the interests of forward compatibility, it is permitted for a 1703 client hello message to include extra data after the compression 1704 methods. This data must be included in the handshake hashes, but 1705 must otherwise be ignored. This is the only handshake message 1706 for which this is legal; for all other messages, the amount of 1707 data in the message must match the description of the message 1708 precisely. 1710 7.4.1.3. Server hello 1712 When this message will be sent: 1713 The server will send this message in response to a client hello 1714 message when it was able to find an acceptable set of 1715 algorithms. If it cannot find such a match, it will respond with 1716 a handshake failure alert. 1718 Structure of this message: 1719 struct { 1720 ProtocolVersion server_version; 1721 Random random; 1722 SessionID session_id; 1723 CipherSuite cipher_suite; 1724 CompressionMethod compression_method; 1725 } ServerHello; 1727 server_version 1728 This field will contain the lower of that suggested by the 1729 client in the client hello and the highest supported by the 1730 server. For this version of the specification, the version is 1731 3.1 (See Appendix E for details about backward compatibility). 1733 random 1734 This structure is generated by the server and must be different 1735 from (and independent of) ClientHello.random. 1737 session_id 1738 This is the identity of the session corresponding to this 1739 connection. If the ClientHello.session_id was non-empty, the 1740 server will look in its session cache for a match. If a match is 1741 found and the server is willing to establish the new connection 1742 using the specified session state, the server will respond with 1743 the same value as was supplied by the client. This indicates a 1744 resumed session and dictates that the parties must proceed 1745 directly to the finished messages. Otherwise this field will 1746 contain a different value identifying the new session. The 1747 server may return an empty session_id to indicate that the 1748 session will not be cached and therefore cannot be resumed. If a 1749 session is resumed, it must be resumed using the same cipher 1750 suite it was originally negotiated with. 1752 cipher_suite 1753 The single cipher suite selected by the server from the list in 1754 ClientHello.cipher_suites. For resumed sessions this field is 1755 the value from the state of the session being resumed. 1757 compression_method 1758 The single compression algorithm selected by the server from the 1759 list in ClientHello.compression_methods. For resumed sessions 1760 this field is the value from the resumed session state. 1762 7.4.2. Server certificate 1764 When this message will be sent: 1765 The server must send a certificate whenever the agreed-upon key 1766 exchange method is not an anonymous one. This message will 1767 always immediately follow the server hello message. 1769 Meaning of this message: 1770 The certificate type must be appropriate for the selected cipher 1771 suite's key exchange algorithm, and is generally an X.509v3 1772 certificate. It must contain a key which matches the key 1773 exchange method, as follows. Unless otherwise specified, the 1774 signing algorithm for the certificate must be the same as the 1775 algorithm for the certificate key. Unless otherwise specified, 1776 the public key may be of any length. 1778 Key Exchange Algorithm Certificate Key Type 1780 RSA RSA public key; the certificate must 1781 allow the key to be used for encryption. 1783 RSA_EXPORT RSA public key of length greater than 1784 512 bits which can be used for signing, 1785 or a key of 512 bits or shorter which 1786 can be used for either encryption or 1787 signing. 1789 DHE_DSS DSS public key. 1791 DHE_DSS_EXPORT DSS public key. 1793 DHE_RSA RSA public key which can be used for 1794 signing. 1796 DHE_RSA_EXPORT RSA public key which can be used for 1797 signing. 1799 DH_DSS Diffie-Hellman key. The algorithm used 1800 to sign the certificate should be DSS. 1802 DH_RSA Diffie-Hellman key. The algorithm used 1803 to sign the certificate should be RSA. 1805 All certificate profiles, key and cryptographic formats are defined 1806 by the IETF PKIX working group [PKIX]. When a key usage extension is 1807 present, the digitalSignature bit must be set for the key to be 1808 eligible for signing, as described above, and the keyEncipherment 1809 bit must be present to allow encryption, as described above. The 1810 keyAgreement bit must be set on Diffie-Hellman certificates. 1812 As CipherSuites which specify new key exchange methods are specified 1813 for the TLS Protocol, they will imply certificate format and the 1814 required encoded keying information. 1816 Structure of this message: 1817 opaque ASN.1Cert<1..2^24-1>; 1819 struct { 1820 ASN.1Cert certificate_list<0..2^24-1>; 1821 } Certificate; 1823 certificate_list 1824 This is a sequence (chain) of X.509v3 certificates. The sender's 1825 certificate must come first in the list. Each following 1826 certificate must directly certify the one preceding it. Because 1827 certificate validation requires that root keys be distributed 1828 independently, the self-signed certificate which specifies the 1829 root certificate authority may optionally be omitted from the 1830 chain, under the assumption that the remote end must already 1831 possess it in order to validate it in any case. 1833 The same message type and structure will be used for the client's 1834 response to a certificate request message. Note that a client may 1835 send no certificates if it does not have an appropriate certificate 1836 to send in response to the server's authentication request. 1838 Note: PKCS #7 [PKCS7] is not used as the format for the certificate 1839 vector because PKCS #6 [PKCS6] extended certificates are not 1840 used. Also PKCS #7 defines a SET rather than a SEQUENCE, making 1841 the task of parsing the list more difficult. 1843 7.4.3. Server key exchange message 1845 When this message will be sent: 1846 This message will be sent immediately after the server 1847 certificate message (or the server hello message, if this is an 1848 anonymous negotiation). 1850 The server key exchange message is sent by the server only when 1851 the server certificate message (if sent) does not contain enough 1852 data to allow the client to exchange a premaster secret. This is 1853 true for the following key exchange methods: 1855 RSA_EXPORT (if the public key in the server certificate is 1856 longer than 512 bits) 1857 DHE_DSS 1858 DHE_DSS_EXPORT 1859 DHE_RSA 1860 DHE_RSA_EXPORT 1861 DH_anon 1863 It is not legal to send the server key exchange message for the 1864 following key exchange methods: 1866 RSA 1867 RSA_EXPORT (when the public key in the server certificate is 1868 less than or equal to 512 bits in length) 1869 DH_DSS 1870 DH_RSA 1872 Meaning of this message: 1873 This message conveys cryptographic information to allow the 1874 client to communicate the premaster secret: either an RSA public 1875 key to encrypt the premaster secret with, or a Diffie-Hellman 1876 public key with which the client can complete a key exchange 1877 (with the result being the premaster secret.) 1879 As additional CipherSuites are defined for TLS which include new key 1880 exchange algorithms, the server key exchange message will be sent if 1881 and only if the certificate type associated with the key exchange 1882 algorithm does not provide enough information for the client to 1883 exchange a premaster secret. 1885 Note: According to current US export law, RSA moduli larger than 512 1886 bits may not be used for key exchange in software exported from 1887 the US. With this message, the larger RSA keys encoded in 1888 certificates may be used to sign temporary shorter RSA keys for 1889 the RSA_EXPORT key exchange method. 1891 Structure of this message: 1892 enum { rsa, diffie_hellman } KeyExchangeAlgorithm; 1894 struct { 1895 opaque rsa_modulus<1..2^16-1>; 1896 opaque rsa_exponent<1..2^16-1>; 1897 } ServerRSAParams; 1898 rsa_modulus 1899 The modulus of the server's temporary RSA key. 1901 rsa_exponent 1902 The public exponent of the server's temporary RSA key. 1904 struct { 1905 opaque dh_p<1..2^16-1>; 1906 opaque dh_g<1..2^16-1>; 1907 opaque dh_Ys<1..2^16-1>; 1908 } ServerDHParams; /* Ephemeral DH parameters */ 1910 dh_p 1911 The prime modulus used for the Diffie-Hellman operation. 1913 dh_g 1914 The generator used for the Diffie-Hellman operation. 1916 dh_Ys 1917 The server's Diffie-Hellman public value (g^X mod p). 1919 struct { 1920 select (KeyExchangeAlgorithm) { 1921 case diffie_hellman: 1922 ServerDHParams params; 1923 Signature signed_params; 1924 case rsa: 1925 ServerRSAParams params; 1926 Signature signed_params; 1927 }; 1928 } ServerKeyExchange; 1930 params 1931 The server's key exchange parameters. 1933 signed_params 1934 For non-anonymous key exchanges, a hash of the corresponding 1935 params value, with the signature appropriate to that hash 1936 applied. 1938 md5_hash 1939 MD5(ClientHello.random + ServerHello.random + ServerParams); 1941 sha_hash 1942 SHA(ClientHello.random + ServerHello.random + ServerParams); 1944 enum { anonymous, rsa, dsa } SignatureAlgorithm; 1946 select (SignatureAlgorithm) 1947 { case anonymous: struct { }; 1948 case rsa: 1949 digitally-signed struct { 1950 opaque md5_hash[16]; 1951 opaque sha_hash[20]; 1952 }; 1953 case dsa: 1954 digitally-signed struct { 1955 opaque sha_hash[20]; 1956 }; 1957 } Signature; 1959 7.4.4. Certificate request 1961 When this message will be sent: 1962 A non-anonymous server can optionally request a certificate from 1963 the client, if appropriate for the selected cipher suite. This 1964 message, if sent, will immediately follow the Server Key 1965 Exchange message (if it is sent; otherwise, the Server 1966 Certificate message). 1968 Structure of this message: 1969 enum { 1970 rsa_sign(1), dss_sign(2), rsa_fixed_dh(3), dss_fixed_dh(4), 1971 (255) 1972 } ClientCertificateType; 1974 opaque DistinguishedName<1..2^16-1>; 1976 struct { 1977 ClientCertificateType certificate_types<1..2^8-1>; 1978 DistinguishedName certificate_authorities<3..2^16-1>; 1979 } CertificateRequest; 1981 certificate_types 1982 This field is a list of the types of certificates requested, 1983 sorted in order of the server's preference. 1985 certificate_authorities 1986 A list of the distinguished names of acceptable certificate 1987 authorities. These distinguished names may specify a desired 1988 distinguished name for a root CA or for a subordinate CA; 1989 thus, this message can be used both to describe known roots 1990 and a desired authorization space. 1992 Note: DistinguishedName is derived from [X509]. 1994 Note: It is a fatal handshake_failure alert for an anonymous server to 1995 request client identification. 1997 7.4.5. Server hello done 1999 When this message will be sent: 2000 The server hello done message is sent by the server to indicate 2001 the end of the server hello and associated messages. After 2002 sending this message the server will wait for a client response. 2004 Meaning of this message: 2005 This message means that the server is done sending messages to 2006 support the key exchange, and the client can proceed with its 2007 phase of the key exchange. 2009 Upon receipt of the server hello done message the client should 2010 verify that the server provided a valid certificate if required 2011 and check that the server hello parameters are acceptable. 2013 Structure of this message: 2014 struct { } ServerHelloDone; 2016 7.4.6. Client certificate 2018 When this message will be sent: 2019 This is the first message the client can send after receiving a 2020 server hello done message. This message is only sent if the 2021 server requests a certificate. If no suitable certificate is 2022 available, the client should send a certificate message 2023 containing no certificates. If client authentication is required 2024 by the server for the handshake to continue, it may respond with 2025 a fatal handshake failure alert. Client certificates are sent 2026 using the Certificate structure defined in Section 7.4.2. 2028 Note: When using a static Diffie-Hellman based key exchange method 2029 (DH_DSS or DH_RSA), if client authentication is requested, the 2030 Diffie-Hellman group and generator encoded in the client's 2031 certificate must match the server specified Diffie-Hellman 2032 parameters if the client's parameters are to be used for the key 2033 exchange. 2035 7.4.7. Client key exchange message 2037 When this message will be sent: 2038 This message is always sent by the client. It will immediately 2039 follow the client certificate message, if it is sent. Otherwise 2040 it will be the first message sent by the client after it 2041 receives the server hello done message. 2043 Meaning of this message: 2044 With this message, the premaster secret is set, either though 2045 direct transmission of the RSA-encrypted secret, or by the 2046 transmission of Diffie-Hellman parameters which will allow each 2047 side to agree upon the same premaster secret. When the key 2048 exchange method is DH_RSA or DH_DSS, client certification has 2049 been requested, and the client was able to respond with a 2050 certificate which contained a Diffie-Hellman public key whose 2051 parameters (group and generator) matched those specified by the 2052 server in its certificate, this message will not contain any 2053 data. 2055 Structure of this message: 2056 The choice of messages depends on which key exchange method has 2057 been selected. See Section 7.4.3 for the KeyExchangeAlgorithm 2058 definition. 2060 struct { 2061 select (KeyExchangeAlgorithm) { 2062 case rsa: EncryptedPreMasterSecret; 2063 case diffie_hellman: ClientDiffieHellmanPublic; 2064 } exchange_keys; 2065 } ClientKeyExchange; 2067 7.4.7.1. RSA encrypted premaster secret message 2069 Meaning of this message: 2070 If RSA is being used for key agreement and authentication, the 2071 client generates a 48-byte premaster secret, encrypts it using 2072 the public key from the server's certificate or the temporary 2073 RSA key provided in a server key exchange message, and sends the 2074 result in an encrypted premaster secret message. This structure 2075 is a variant of the client key exchange message, not a message 2076 in itself. 2078 Structure of this message: 2079 struct { 2080 ProtocolVersion client_version; 2081 opaque random[46]; 2082 } PreMasterSecret; 2084 client_version 2085 The latest (newest) version supported by the client. This is 2086 used to detect version roll-back attacks. Upon receiving the 2087 premaster secret, the server should check that this value 2088 matches the value transmitted by the client in the client 2089 hello message. 2091 random 2092 46 securely-generated random bytes. 2094 struct { 2095 public-key-encrypted PreMasterSecret pre_master_secret; 2096 } EncryptedPreMasterSecret; 2098 Note: An attack discovered by Daniel Bleichenbacher [BLEI] can be used 2099 to attack a TLS server which is using PKCS#1 encoded RSA. The 2100 attack takes advantage of the fact that by failing in different 2101 ways, a TLS server can be coerced into revealing whether a 2102 particular message, when decrypted, is properly PKCS#1 formatted 2103 or not. 2105 The best way to avoid vulnerability to this attack is to treat 2106 incorrectly formatted messages in a manner indistinguishable 2107 from correctly formatted RSA blocks. Thus, when it receives an 2108 incorrectly formatted RSA block, a server should generate a 2109 random 48-byte value and proceed using it as the premaster 2110 secret. Thus, the server will act identically whether the 2111 received RSA block is correctly encoded or not. 2113 pre_master_secret 2114 This random value is generated by the client and is used to 2115 generate the master secret, as specified in Section 8.1. 2117 7.4.7.2. Client Diffie-Hellman public value 2119 Meaning of this message: 2120 This structure conveys the client's Diffie-Hellman public value 2121 (Yc) if it was not already included in the client's certificate. 2122 The encoding used for Yc is determined by the enumerated 2123 PublicValueEncoding. This structure is a variant of the client 2124 key exchange message, not a message in itself. 2126 Structure of this message: 2127 enum { implicit, explicit } PublicValueEncoding; 2129 implicit 2130 If the client certificate already contains a suitable 2131 Diffie-Hellman key, then Yc is implicit and does not need to 2132 be sent again. In this case, the Client Key Exchange message 2133 will be sent, but will be empty. 2135 explicit 2136 Yc needs to be sent. 2138 struct { 2139 select (PublicValueEncoding) { 2140 case implicit: struct { }; 2141 case explicit: opaque dh_Yc<1..2^16-1>; 2142 } dh_public; 2143 } ClientDiffieHellmanPublic; 2145 dh_Yc 2146 The client's Diffie-Hellman public value (Yc). 2148 7.4.8. Certificate verify 2150 When this message will be sent: 2151 This message is used to provide explicit verification of a 2152 client certificate. This message is only sent following a client 2153 certificate that has signing capability (i.e. all certificates 2154 except those containing fixed Diffie-Hellman parameters). When 2155 sent, it will immediately follow the client key exchange 2156 message. 2158 Structure of this message: 2159 struct { 2160 Signature signature; 2161 } CertificateVerify; 2163 The Signature type is defined in 6.4.3. 2165 CertificateVerify.signature.md5_hash 2166 MD5(handshake_messages); 2168 Certificate.signature.sha_hash 2169 SHA(handshake_messages); 2171 Here handshake_messages refers to all handshake messages sent or 2172 received starting at client hello up to but not including this 2173 message, including the type and length fields of the handshake 2174 messages. This is the concatenation of all the Handshake structures 2175 as defined in 7.4 exchanged thus far. 2177 7.4.9. Finished 2179 When this message will be sent: 2180 A finished message is always sent immediately after a change 2181 cipher spec message to verify that the key exchange and 2182 authentication processes were successful. It is essential that a 2183 change cipher spec message be received between the other 2184 handshake messages and the Finished message. 2186 Meaning of this message: 2187 The finished message is the first protected with the 2188 just-negotiated algorithms, keys, and secrets. Recipients of 2189 finished messages must verify that the contents are correct. 2190 Once a side has sent its Finished message and received and 2191 validated the Finished message from its peer, it may begin to 2192 send and receive application data over the connection. 2194 struct { 2195 opaque verify_data[12]; 2196 } Finished; 2198 verify_data 2199 PRF(master_secret, finished_label, MD5(handshake_messages) + 2200 SHA-1(handshake_messages)) [0..11]; 2202 finished_label 2203 For Finished messages sent by the client, the string "client 2204 finished". For Finished messages sent by the server, the 2205 string "server finished". 2207 handshake_messages 2208 All of the data from all handshake messages up to but not 2209 including this message. This is only data visible at the 2210 handshake layer and does not include record layer headers. 2211 This is the concatenation of all the Handshake structures as 2212 defined in 7.4 exchanged thus far. 2214 It is a fatal error if a finished message is not preceded by a 2215 change cipher spec message at the appropriate point in the 2216 handshake. 2218 The hash contained in finished messages sent by the server 2219 incorporate Sender.server; those sent by the client incorporate 2220 Sender.client. The value handshake_messages includes all handshake 2221 messages starting at client hello up to, but not including, this 2222 finished message. This may be different from handshake_messages in 2223 Section 7.4.8 because it would include the certificate verify 2224 message (if sent). Also, the handshake_messages for the finished 2225 message sent by the client will be different from that for the 2226 finished message sent by the server, because the one which is sent 2227 second will include the prior one. 2229 Note: Change cipher spec messages, alerts and any other record types 2230 are not handshake messages and are not included in the hash 2231 computations. Also, Hello Request messages are omitted from 2232 handshake hashes. 2234 8. Cryptographic computations 2236 In order to begin connection protection, the TLS Record Protocol 2237 requires specification of a suite of algorithms, a master secret, 2238 and the client and server random values. The authentication, 2239 encryption, and MAC algorithms are determined by the cipher_suite 2240 selected by the server and revealed in the server hello message. The 2241 compression algorithm is negotiated in the hello messages, and the 2242 random values are exchanged in the hello messages. All that remains 2243 is to calculate the master secret. 2245 8.1. Computing the master secret 2247 For all key exchange methods, the same algorithm is used to convert 2248 the pre_master_secret into the master_secret. The pre_master_secret 2249 should be deleted from memory once the master_secret has been 2250 computed. 2252 master_secret = PRF(pre_master_secret, "master secret", 2253 ClientHello.random + ServerHello.random) 2254 [0..47]; 2256 The master secret is always exactly 48 bytes in length. The length 2257 of the premaster secret will vary depending on key exchange method. 2259 8.1.1. RSA 2261 When RSA is used for server authentication and key exchange, a 2262 48-byte pre_master_secret is generated by the client, encrypted 2263 under the server's public key, and sent to the server. The server 2264 uses its private key to decrypt the pre_master_secret. Both parties 2265 then convert the pre_master_secret into the master_secret, as 2266 specified above. 2268 RSA digital signatures are performed using PKCS #1 [PKCS1] block 2269 type 1. RSA public key encryption is performed using PKCS #1 block 2270 type 2. 2272 8.1.2. Diffie-Hellman 2274 A conventional Diffie-Hellman computation is performed. The 2275 negotiated key (Z) is used as the pre_master_secret, and is 2276 converted into the master_secret, as specified above. 2278 Note: Diffie-Hellman parameters are specified by the server, and may 2279 be either ephemeral or contained within the server's 2280 certificate. 2282 9. Mandatory Cipher Suites 2284 In the absence of an application profile standard specifying 2285 otherwise, a TLS compliant application MUST implement the cipher 2286 suite TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA. 2288 10. Application data protocol 2290 Application data messages are carried by the Record Layer and are 2291 fragmented, compressed and encrypted based on the current connection 2292 state. The messages are treated as transparent data to the record 2293 layer. 2295 A. Protocol constant values 2297 This section describes protocol types and constants. 2299 A.1. Record layer 2301 struct { 2302 uint8 major, minor; 2303 } ProtocolVersion; 2305 ProtocolVersion version = { 3, 1 }; /* TLS v1.0 */ 2307 enum { 2308 change_cipher_spec(20), alert(21), handshake(22), 2309 application_data(23), (255) 2310 } ContentType; 2312 struct { 2313 ContentType type; 2314 ProtocolVersion version; 2315 uint16 length; 2316 opaque fragment[TLSPlaintext.length]; 2317 } TLSPlaintext; 2319 struct { 2320 ContentType type; 2321 ProtocolVersion version; 2322 uint16 length; 2323 opaque fragment[TLSCompressed.length]; 2324 } TLSCompressed; 2326 struct { 2327 ContentType type; 2328 ProtocolVersion version; 2329 uint16 length; 2330 select (CipherSpec.cipher_type) { 2331 case stream: GenericStreamCipher; 2332 case block: GenericBlockCipher; 2333 } fragment; 2334 } TLSCiphertext; 2336 stream-ciphered struct { 2337 opaque content[TLSCompressed.length]; 2338 opaque MAC[CipherSpec.hash_size]; 2339 } GenericStreamCipher; 2341 block-ciphered struct { 2342 opaque content[TLSCompressed.length]; 2343 opaque MAC[CipherSpec.hash_size]; 2344 uint8 padding[GenericBlockCipher.padding_length]; 2345 uint8 padding_length; 2346 } GenericBlockCipher; 2348 A.2. Change cipher specs message 2350 struct { 2351 enum { change_cipher_spec(1), (255) } type; 2352 } ChangeCipherSpec; 2354 A.3. Alert messages 2356 enum { warning(1), fatal(2), (255) } AlertLevel; 2358 enum { 2359 close_notify(0), 2360 unexpected_message(10), 2361 bad_record_mac(20), 2362 decryption_failed(21), 2363 record_overflow(22), 2364 decompression_failure(30), 2365 handshake_failure(40), 2366 bad_certificate(42), 2367 unsupported_certificate(43), 2368 certificate_revoked(44), 2369 certificate_expired(45), 2370 certificate_unknown(46), 2371 illegal_parameter(47), 2372 unknown_ca(48), 2373 access_denied(49), 2374 decode_error(50), 2375 decrypt_error(51), 2376 export_restriction(60), 2377 protocol_version(70), 2378 insufficient_security(71), 2379 internal_error(80), 2380 user_canceled(90), 2381 no_renegotiation(100), 2382 (255) 2383 } AlertDescription; 2385 struct { 2386 AlertLevel level; 2387 AlertDescription description; 2388 } Alert; 2390 A.4. Handshake protocol 2392 enum { 2393 hello_request(0), client_hello(1), server_hello(2), 2394 certificate(11), server_key_exchange (12), 2395 certificate_request(13), server_hello_done(14), 2396 certificate_verify(15), client_key_exchange(16), 2397 finished(20), (255) 2398 } HandshakeType; 2400 struct { 2401 HandshakeType msg_type; 2402 uint24 length; 2403 select (HandshakeType) { 2404 case hello_request: HelloRequest; 2405 case client_hello: ClientHello; 2406 case server_hello: ServerHello; 2407 case certificate: Certificate; 2408 case server_key_exchange: ServerKeyExchange; 2409 case certificate_request: CertificateRequest; 2410 case server_hello_done: ServerHelloDone; 2411 case certificate_verify: CertificateVerify; 2412 case client_key_exchange: ClientKeyExchange; 2413 case finished: Finished; 2414 } body; 2415 } Handshake; 2417 A.4.1. Hello messages 2419 struct { } HelloRequest; 2421 struct { 2422 uint32 gmt_unix_time; 2423 opaque random_bytes[28]; 2424 } Random; 2426 opaque SessionID<0..32>; 2428 uint8 CipherSuite[2]; 2430 enum { null(0), (255) } CompressionMethod; 2432 struct { 2433 ProtocolVersion client_version; 2434 Random random; 2435 SessionID session_id; 2436 CipherSuite cipher_suites<2..2^16-1>; 2437 CompressionMethod compression_methods<1..2^8-1>; 2438 } ClientHello; 2440 struct { 2441 ProtocolVersion server_version; 2442 Random random; 2443 SessionID session_id; 2444 CipherSuite cipher_suite; 2445 CompressionMethod compression_method; 2446 } ServerHello; 2448 A.4.2. Server authentication and key exchange messages 2450 opaque ASN.1Cert<2^24-1>; 2452 struct { 2453 ASN.1Cert certificate_list<1..2^24-1>; 2454 } Certificate; 2456 enum { rsa, diffie_hellman } KeyExchangeAlgorithm; 2458 struct { 2459 opaque RSA_modulus<1..2^16-1>; 2460 opaque RSA_exponent<1..2^16-1>; 2461 } ServerRSAParams; 2463 struct { 2464 opaque DH_p<1..2^16-1>; 2465 opaque DH_g<1..2^16-1>; 2466 opaque DH_Ys<1..2^16-1>; 2467 } ServerDHParams; 2468 struct { 2469 select (KeyExchangeAlgorithm) { 2470 case diffie_hellman: 2471 ServerDHParams params; 2472 Signature signed_params; 2473 case rsa: 2474 ServerRSAParams params; 2475 Signature signed_params; 2476 }; 2477 } ServerKeyExchange; 2479 enum { anonymous, rsa, dsa } SignatureAlgorithm; 2481 select (SignatureAlgorithm) 2482 { case anonymous: struct { }; 2483 case rsa: 2484 digitally-signed struct { 2485 opaque md5_hash[16]; 2486 opaque sha_hash[20]; 2487 }; 2488 case dsa: 2489 digitally-signed struct { 2490 opaque sha_hash[20]; 2491 }; 2492 } Signature; 2494 enum { 2495 rsa_sign(1), dss_sign(2), rsa_fixed_dh(3), dss_fixed_dh(4), 2496 (255) 2497 } ClientCertificateType; 2499 opaque DistinguishedName<1..2^16-1>; 2501 struct { 2502 ClientCertificateType certificate_types<1..2^8-1>; 2503 DistinguishedName certificate_authorities<3..2^16-1>; 2504 } CertificateRequest; 2506 struct { } ServerHelloDone; 2508 A.4.3. Client authentication and key exchange messages 2510 struct { 2511 select (KeyExchangeAlgorithm) { 2512 case rsa: EncryptedPreMasterSecret; 2513 case diffie_hellman: DiffieHellmanClientPublicValue; 2514 } exchange_keys; 2515 } ClientKeyExchange; 2517 struct { 2518 ProtocolVersion client_version; 2519 opaque random[46]; 2521 } PreMasterSecret; 2523 struct { 2524 public-key-encrypted PreMasterSecret pre_master_secret; 2525 } EncryptedPreMasterSecret; 2527 enum { implicit, explicit } PublicValueEncoding; 2529 struct { 2530 select (PublicValueEncoding) { 2531 case implicit: struct {}; 2532 case explicit: opaque DH_Yc<1..2^16-1>; 2533 } dh_public; 2534 } ClientDiffieHellmanPublic; 2536 struct { 2537 Signature signature; 2538 } CertificateVerify; 2540 A.4.4. Handshake finalization message 2542 struct { 2543 opaque verify_data[12]; 2544 } Finished; 2546 A.5. The CipherSuite 2548 The following values define the CipherSuite codes used in the client 2549 hello and server hello messages. 2551 A CipherSuite defines a cipher specification supported in TLS 2552 Version 1.0. 2554 TLS_NULL_WITH_NULL_NULL is specified and is the initial state of a 2555 TLS connection during the first handshake on that channel, but must 2556 not be negotiated, as it provides no more protection than an 2557 unsecured connection. 2559 CipherSuite TLS_NULL_WITH_NULL_NULL = { 0x00,0x00 }; 2561 The following CipherSuite definitions require that the server 2562 provide an RSA certificate that can be used for key exchange. The 2563 server may request either an RSA or a DSS signature-capable 2564 certificate in the certificate request message. 2566 CipherSuite TLS_RSA_WITH_NULL_MD5 = { 0x00,0x01 }; 2567 CipherSuite TLS_RSA_WITH_NULL_SHA = { 0x00,0x02 }; 2568 CipherSuite TLS_RSA_EXPORT_WITH_RC4_40_MD5 = { 0x00,0x03 }; 2569 CipherSuite TLS_RSA_WITH_RC4_128_MD5 = { 0x00,0x04 }; 2570 CipherSuite TLS_RSA_WITH_RC4_128_SHA = { 0x00,0x05 }; 2571 CipherSuite TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 = { 0x00,0x06 }; 2572 CipherSuite TLS_RSA_WITH_IDEA_CBC_SHA = { 0x00,0x07 }; 2573 CipherSuite TLS_RSA_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x08 }; 2574 CipherSuite TLS_RSA_WITH_DES_CBC_SHA = { 0x00,0x09 }; 2575 CipherSuite TLS_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x0A }; 2577 The following CipherSuite definitions are used for 2578 server-authenticated (and optionally client-authenticated) 2579 Diffie-Hellman. DH denotes cipher suites in which the server's 2580 certificate contains the Diffie-Hellman parameters signed by the 2581 certificate authority (CA). DHE denotes ephemeral Diffie-Hellman, 2582 where the Diffie-Hellman parameters are signed by a DSS or RSA 2583 certificate, which has been signed by the CA. The signing algorithm 2584 used is specified after the DH or DHE parameter. The server can 2585 request an RSA or DSS signature-capable certificate from the client 2586 for client authentication or it may request a Diffie-Hellman 2587 certificate. Any Diffie-Hellman certificate provided by the client 2588 must use the parameters (group and generator) described by the 2589 server. 2591 CipherSuite TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x0B }; 2592 CipherSuite TLS_DH_DSS_WITH_DES_CBC_SHA = { 0x00,0x0C }; 2593 CipherSuite TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA = { 0x00,0x0D }; 2594 CipherSuite TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x0E }; 2595 CipherSuite TLS_DH_RSA_WITH_DES_CBC_SHA = { 0x00,0x0F }; 2596 CipherSuite TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x10 }; 2597 CipherSuite TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x11 }; 2598 CipherSuite TLS_DHE_DSS_WITH_DES_CBC_SHA = { 0x00,0x12 }; 2599 CipherSuite TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA = { 0x00,0x13 }; 2600 CipherSuite TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x14 }; 2601 CipherSuite TLS_DHE_RSA_WITH_DES_CBC_SHA = { 0x00,0x15 }; 2602 CipherSuite TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x16 }; 2604 The following cipher suites are used for completely anonymous 2605 Diffie-Hellman communications in which neither party is 2606 authenticated. Note that this mode is vulnerable to 2607 man-in-the-middle attacks and is therefore deprecated. 2609 CipherSuite TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 = { 0x00,0x17 }; 2610 CipherSuite TLS_DH_anon_WITH_RC4_128_MD5 = { 0x00,0x18 }; 2611 CipherSuite TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x19 }; 2612 CipherSuite TLS_DH_anon_WITH_DES_CBC_SHA = { 0x00,0x1A }; 2613 CipherSuite TLS_DH_anon_WITH_3DES_EDE_CBC_SHA = { 0x00,0x1B }; 2615 Note: All cipher suites whose first byte is 0xFF are considered 2616 private and can be used for defining local/experimental 2617 algorithms. Interoperability of such types is a local matter. 2619 Note: Additional cipher suites can be registered by publishing an RFC 2620 which specifies the cipher suites, including the necessary TLS 2621 protocol information, including message encoding, premaster 2622 secret derivation, symmetric encryption and MAC calculation and 2623 appropriate reference information for the algorithms involved. 2624 The RFC editor's office may, at its discretion, choose to 2625 publish specifications for cipher suites which are not 2626 completely described (e.g., for classified algorithms) if it 2627 finds the specification to be of technical interest and 2628 completely specified. 2630 Note: The cipher suite values { 0x00, 0x1C } and { 0x00, 0x1D } are 2631 reserved to avoid collision with Fortezza-based cipher suites in 2632 SSL 3. 2634 A.6. The Security Parameters 2636 These security parameters are determined by the TLS Handshake 2637 Protocol and provided as parameters to the TLS Record Layer in order 2638 to initialize a connection state. SecurityParameters includes: 2640 enum { null(0), (255) } CompressionMethod; 2642 enum { server, client } ConnectionEnd; 2644 enum { null, rc4, rc2, des, 3des, des40, idea } 2645 BulkCipherAlgorithm; 2647 enum { stream, block } CipherType; 2649 enum { true, false } IsExportable; 2651 enum { null, md5, sha } MACAlgorithm; 2653 /* The algorithms specified in CompressionMethod, 2654 BulkCipherAlgorithm, and MACAlgorithm may be added to. */ 2656 struct { 2657 ConnectionEnd entity; 2658 BulkCipherAlgorithm bulk_cipher_algorithm; 2659 CipherType cipher_type; 2660 uint8 key_size; 2661 uint8 key_material_length; 2662 IsExportable is_exportable; 2663 MACAlgorithm mac_algorithm; 2664 uint8 hash_size; 2665 CompressionMethod compression_algorithm; 2666 opaque master_secret[48]; 2667 opaque client_random[32]; 2668 opaque server_random[32]; 2669 } SecurityParameters; 2671 B. Glossary 2673 application protocol 2674 An application protocol is a protocol that normally layers 2675 directly on top of the transport layer (e.g., TCP/IP). Examples 2676 include HTTP, TELNET, FTP, and SMTP. 2678 asymmetric cipher 2679 See public key cryptography. 2681 authentication 2682 Authentication is the ability of one entity to determine the 2683 identity of another entity. 2685 block cipher 2686 A block cipher is an algorithm that operates on plaintext in 2687 groups of bits, called blocks. 64 bits is a common block size. 2689 bulk cipher 2690 A symmetric encryption algorithm used to encrypt large 2691 quantities of data. 2693 cipher block chaining (CBC) 2694 CBC is a mode in which every plaintext block encrypted with a 2695 block cipher is first exclusive-ORed with the previous 2696 ciphertext block (or, in the case of the first block, with the 2697 initialization vector). For decryption, every block is first 2698 decrypted, then exclusive-ORed with the previous ciphertext 2699 block (or IV). 2701 certificate 2702 As part of the X.509 protocol (a.k.a. ISO Authentication 2703 framework), certificates are assigned by a trusted Certificate 2704 Authority and provide a strong binding between a party's 2705 identity or some other attributes and its public key. 2707 client 2708 The application entity that initiates a TLS connection to a 2709 server. This may or may not imply that the client initiated the 2710 underlying transport connection. The primary operational 2711 difference between the server and client is that the server is 2712 generally authenticated, while the client is only optionally 2713 authenticated. 2715 client write key 2716 The key used to encrypt data written by the client. 2718 client write MAC secret 2719 The secret data used to authenticate data written by the client. 2721 connection 2722 A connection is a transport (in the OSI layering model 2723 definition) that provides a suitable type of service. For TLS, 2724 such connections are peer to peer relationships. The connections 2725 are transient. Every connection is associated with one session. 2727 Data Encryption Standard 2728 DES is a very widely used symmetric encryption algorithm. DES is 2729 a block cipher with a 56 bit key and an 8 byte block size. Note 2730 that in TLS, for key generation purposes, DES is treated as 2731 having an 8 byte key length (64 bits), but it still only 2732 provides 56 bits of protection. (The low bit of each key byte is 2733 presumed to be set to produce odd parity in that key byte.) DES 2734 can also be operated in a mode where three independent keys and 2735 three encryptions are used for each block of data; this uses 168 2736 bits of key (24 bytes in the TLS key generation method) and 2737 provides the equivalent of 112 bits of security. [DES], [3DES] 2739 Digital Signature Standard (DSS) 2740 A standard for digital signing, including the Digital Signing 2741 Algorithm, approved by the National Institute of Standards and 2742 Technology, defined in NIST FIPS PUB 186, "Digital Signature 2743 Standard," published May, 1994 by the U.S. Dept. of Commerce. 2744 [DSS] 2746 digital signatures 2747 Digital signatures utilize public key cryptography and one-way 2748 hash functions to produce a signature of the data that can be 2749 authenticated, and is difficult to forge or repudiate. 2751 handshake 2752 An initial negotiation between client and server that 2753 establishes the parameters of their transactions. 2755 Initialization Vector (IV) 2756 When a block cipher is used in CBC mode, the initialization 2757 vector is exclusive-ORed with the first plaintext block prior to 2758 encryption. 2760 IDEA 2761 A 64-bit block cipher designed by Xuejia Lai and James Massey. 2762 [IDEA] 2764 Message Authentication Code (MAC) 2765 A Message Authentication Code is a one-way hash computed from a 2766 message and some secret data. It is difficult to forge without 2767 knowing the secret data. Its purpose is to detect if the message 2768 has been altered. 2770 master secret 2771 Secure secret data used for generating encryption keys, MAC 2772 secrets, and IVs. 2774 MD5 2775 MD5 is a secure hashing function that converts an arbitrarily 2776 long data stream into a digest of fixed size (16 bytes). [MD5] 2778 public key cryptography 2779 A class of cryptographic techniques employing two-key ciphers. 2780 Messages encrypted with the public key can only be decrypted 2781 with the associated private key. Conversely, messages signed 2782 with the private key can be verified with the public key. 2784 one-way hash function 2785 A one-way transformation that converts an arbitrary amount of 2786 data into a fixed-length hash. It is computationally hard to 2787 reverse the transformation or to find collisions. MD5 and SHA 2788 are examples of one-way hash functions. 2790 RC2 2791 A block cipher developed by Ron Rivest at RSA Data Security, 2792 Inc. [RSADSI] described in [RC2]. 2794 RC4 2795 A stream cipher licensed by RSA Data Security [RSADSI]. A 2796 compatible cipher is described in [RC4]. 2798 RSA 2799 A very widely used public-key algorithm that can be used for 2800 either encryption or digital signing. [RSA] 2802 salt 2803 Non-secret random data used to make export encryption keys 2804 resist precomputation attacks. 2806 server 2807 The server is the application entity that responds to requests 2808 for connections from clients. See also under client. 2810 session 2811 A TLS session is an association between a client and a server. 2812 Sessions are created by the handshake protocol. Sessions define 2813 a set of cryptographic security parameters, which can be shared 2814 among multiple connections. Sessions are used to avoid the 2815 expensive negotiation of new security parameters for each 2816 connection. 2818 session identifier 2819 A session identifier is a value generated by a server that 2820 identifies a particular session. 2822 server write key 2823 The key used to encrypt data written by the server. 2825 server write MAC secret 2826 The secret data used to authenticate data written by the server. 2828 SHA 2829 The Secure Hash Algorithm is defined in FIPS PUB 180-1. It 2830 produces a 20-byte output. Note that all references to SHA 2831 actually use the modified SHA-1 algorithm. [SHA] 2833 SSL 2834 Netscape's Secure Socket Layer protocol [SSL3]. TLS is based on 2835 SSL Version 3.0 2837 stream cipher 2838 An encryption algorithm that converts a key into a 2839 cryptographically-strong keystream, which is then exclusive-ORed 2840 with the plaintext. 2842 symmetric cipher 2843 See bulk cipher. 2845 Transport Layer Security (TLS) 2846 This protocol; also, the Transport Layer Security working group 2847 of the Internet Engineering Task Force (IETF). See "Comments" at 2848 the end of this document. 2850 C. CipherSuite definitions 2852 CipherSuite Is Key Cipher Hash 2853 Exportable Exchange 2855 TLS_NULL_WITH_NULL_NULL * NULL NULL NULL 2856 TLS_RSA_WITH_NULL_MD5 * RSA NULL MD5 2857 TLS_RSA_WITH_NULL_SHA * RSA NULL SHA 2858 TLS_RSA_EXPORT_WITH_RC4_40_MD5 * RSA_EXPORT RC4_40 MD5 2859 TLS_RSA_WITH_RC4_128_MD5 RSA RC4_128 MD5 2860 TLS_RSA_WITH_RC4_128_SHA RSA RC4_128 SHA 2861 TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 * RSA_EXPORT RC2_CBC_40 MD5 2862 TLS_RSA_WITH_IDEA_CBC_SHA RSA IDEA_CBC SHA 2863 TLS_RSA_EXPORT_WITH_DES40_CBC_SHA * RSA_EXPORT DES40_CBC SHA 2864 TLS_RSA_WITH_DES_CBC_SHA RSA DES_CBC SHA 2865 TLS_RSA_WITH_3DES_EDE_CBC_SHA RSA 3DES_EDE_CBC SHA 2866 TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA * DH_DSS_EXPORT DES40_CBC SHA 2867 TLS_DH_DSS_WITH_DES_CBC_SHA DH_DSS DES_CBC SHA 2868 TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA DH_DSS 3DES_EDE_CBC SHA 2869 TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA * DH_RSA_EXPORT DES40_CBC SHA 2870 TLS_DH_RSA_WITH_DES_CBC_SHA DH_RSA DES_CBC SHA 2871 TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA DH_RSA 3DES_EDE_CBC SHA 2872 TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA * DHE_DSS_EXPORT DES40_CBC SHA 2873 TLS_DHE_DSS_WITH_DES_CBC_SHA DHE_DSS DES_CBC SHA 2874 TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE_DSS 3DES_EDE_CBC SHA 2875 TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA * DHE_RSA_EXPORT DES40_CBC SHA 2876 TLS_DHE_RSA_WITH_DES_CBC_SHA DHE_RSA DES_CBC SHA 2877 TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE_RSA 3DES_EDE_CBC SHA 2878 TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 * DH_anon_EXPORT RC4_40 MD5 2879 TLS_DH_anon_WITH_RC4_128_MD5 DH_anon RC4_128 MD5 2880 TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA DH_anon DES40_CBC SHA 2881 TLS_DH_anon_WITH_DES_CBC_SHA DH_anon DES_CBC SHA 2882 TLS_DH_anon_WITH_3DES_EDE_CBC_SHA DH_anon 3DES_EDE_CBC SHA 2883 * Indicates IsExportable is True 2885 Key 2886 Exchange 2887 Algorithm Description Key size limit 2889 DHE_DSS Ephemeral DH with DSS signatures None 2890 DHE_DSS_EXPORT Ephemeral DH with DSS signatures DH = 512 bits 2891 DHE_RSA Ephemeral DH with RSA signatures None 2892 DHE_RSA_EXPORT Ephemeral DH with RSA signatures DH = 512 bits, 2893 RSA = none 2894 DH_anon Anonymous DH, no signatures None 2895 DH_anon_EXPORT Anonymous DH, no signatures DH = 512 bits 2896 DH_DSS DH with DSS-based certificates None 2897 DH_DSS_EXPORT DH with DSS-based certificates DH = 512 bits 2898 DH_RSA DH with RSA-based certificates None 2899 DH_RSA_EXPORT DH with RSA-based certificates DH = 512 bits, 2900 RSA = none 2901 NULL No key exchange N/A 2902 RSA RSA key exchange None 2903 RSA_EXPORT RSA key exchange RSA = 512 bits 2905 Key size limit 2906 The key size limit gives the size of the largest public key that 2907 can be legally used for encryption in cipher suites that are 2908 exportable. 2910 Key Expanded Effective IV Block 2911 Cipher Type Material Key Material Key Bits Size Size 2913 NULL * Stream 0 0 0 0 N/A 2914 IDEA_CBC Block 16 16 128 8 8 2915 RC2_CBC_40 * Block 5 16 40 8 8 2916 RC4_40 * Stream 5 16 40 0 N/A 2917 RC4_128 Stream 16 16 128 0 N/A 2918 DES40_CBC * Block 5 8 40 8 8 2919 DES_CBC Block 8 8 56 8 8 2920 3DES_EDE_CBC Block 24 24 168 8 8 2922 * Indicates IsExportable is true. 2924 Type 2925 Indicates whether this is a stream cipher or a block cipher 2926 running in CBC mode. 2928 Key Material 2929 The number of bytes from the key_block that are used for 2930 generating the write keys. 2932 Expanded Key Material 2933 The number of bytes actually fed into the encryption algorithm 2935 Effective Key Bits 2936 How much entropy material is in the key material being fed into 2937 the encryption routines. 2939 IV Size 2940 How much data needs to be generated for the initialization 2941 vector. Zero for stream ciphers; equal to the block size for 2942 block ciphers. 2944 Block Size 2945 The amount of data a block cipher enciphers in one chunk; a 2946 block cipher running in CBC mode can only encrypt an even 2947 multiple of its block size. 2949 Hash Hash Padding 2950 function Size Size 2951 NULL 0 0 2952 MD5 16 48 2953 SHA 20 40 2955 Appendix D 2957 D. Implementation Notes 2959 The TLS protocol cannot prevent many common security mistakes. This 2960 section provides several recommendations to assist implementors. 2962 D.1. Temporary RSA keys 2964 US Export restrictions limit RSA keys used for encryption to 512 2965 bits, but do not place any limit on lengths of RSA keys used for 2966 signing operations. Certificates often need to be larger than 512 2967 bits, since 512-bit RSA keys are not secure enough for high-value 2968 transactions or for applications requiring long-term security. Some 2969 certificates are also designated signing-only, in which case they 2970 cannot be used for key exchange. 2972 When the public key in the certificate cannot be used for 2973 encryption, the server signs a temporary RSA key, which is then 2974 exchanged. In exportable applications, the temporary RSA key should 2975 be the maximum allowable length (i.e., 512 bits). Because 512-bit 2976 RSA keys are relatively insecure, they should be changed often. For 2977 typical electronic commerce applications, it is suggested that keys 2978 be changed daily or every 500 transactions, and more often if 2979 possible. Note that while it is acceptable to use the same temporary 2980 key for multiple transactions, it must be signed each time it is 2981 used. 2983 RSA key generation is a time-consuming process. In many cases, a 2984 low-priority process can be assigned the task of key generation. 2986 Whenever a new key is completed, the existing temporary key can be 2987 replaced with the new one. 2989 D.2. Random Number Generation and Seeding 2991 TLS requires a cryptographically-secure pseudorandom number 2992 generator (PRNG). Care must be taken in designing and seeding PRNGs. 2993 PRNGs based on secure hash operations, most notably MD5 and/or SHA, 2994 are acceptable, but cannot provide more security than the size of 2995 the random number generator state. (For example, MD5-based PRNGs 2996 usually provide 128 bits of state.) 2998 To estimate the amount of seed material being produced, add the 2999 number of bits of unpredictable information in each seed byte. For 3000 example, keystroke timing values taken from a PC compatible's 18.2 3001 Hz timer provide 1 or 2 secure bits each, even though the total size 3002 of the counter value is 16 bits or more. To seed a 128-bit PRNG, one 3003 would thus require approximately 100 such timer values. 3005 Warning: The seeding functions in RSAREF and versions of BSAFE prior to 3006 3.0 are order-independent. For example, if 1000 seed bits are 3007 supplied, one at a time, in 1000 separate calls to the seed 3008 function, the PRNG will end up in a state which depends only 3009 on the number of 0 or 1 seed bits in the seed data (i.e., 3010 there are 1001 possible final states). Applications using 3011 BSAFE or RSAREF must take extra care to ensure proper seeding. 3012 This may be accomplished by accumulating seed bits into a 3013 buffer and processing them all at once or by processing an 3014 incrementing counter with every seed bit; either method will 3015 reintroduce order dependence into the seeding process. 3017 D.3. Certificates and authentication 3019 Implementations are responsible for verifying the integrity of 3020 certificates and should generally support certificate revocation 3021 messages. Certificates should always be verified to ensure proper 3022 signing by a trusted Certificate Authority (CA). The selection and 3023 addition of trusted CAs should be done very carefully. Users should 3024 be able to view information about the certificate and root CA. 3026 D.4. CipherSuites 3028 TLS supports a range of key sizes and security levels, including 3029 some which provide no or minimal security. A proper implementation 3030 will probably not support many cipher suites. For example, 40-bit 3031 encryption is easily broken, so implementations requiring strong 3032 security should not allow 40-bit keys. Similarly, anonymous 3033 Diffie-Hellman is strongly discouraged because it cannot prevent 3034 man-in-the-middle attacks. Applications should also enforce minimum 3035 and maximum key sizes. For example, certificate chains containing 3036 512-bit RSA keys or signatures are not appropriate for high-security 3037 applications. 3039 E. Backward Compatibility With SSL 3041 For historical reasons and in order to avoid a profligate 3042 consumption of reserved port numbers, application protocols which 3043 are secured by TLS 1.0, SSL 3.0, and SSL 2.0 all frequently share 3044 the same connection port: for example, the https protocol (HTTP 3045 secured by SSL or TLS) uses port 443 regardless of which security 3046 protocol it is using. Thus, some mechanism must be determined to 3047 distinguish and negotiate among the various protocols. 3049 TLS version 1.0 and SSL 3.0 are very similar; thus, supporting both 3050 is easy. TLS clients who wish to negotiate with SSL 3.0 servers 3051 should send client hello messages using the SSL 3.0 record format 3052 and client hello structure, sending {3, 1} for the version field to 3053 note that they support TLS 1.0. If the server supports only SSL 3.0, 3054 it will respond with an SSL 3.0 server hello; if it supports TLS, 3055 with a TLS server hello. The negotiation then proceeds as 3056 appropriate for the negotiated protocol. 3058 Similarly, a TLS server which wishes to interoperate with SSL 3.0 3059 clients should accept SSL 3.0 client hello messages and respond with 3060 an SSL 3.0 server hello if an SSL 3.0 client hello is received which 3061 has a version field of {3, 0}, denoting that this client does not 3062 support TLS. 3064 Whenever a client already knows the highest protocol known to a 3065 server (for example, when resuming a session), it should initiate 3066 the connection in that native protocol. 3068 TLS 1.0 clients that support SSL Version 2.0 servers must send SSL 3069 Version 2.0 client hello messages [SSL2]. TLS servers should accept 3070 either client hello format if they wish to support SSL 2.0 clients 3071 on the same connection port. The only deviations from the Version 3072 2.0 specification are the ability to specify a version with a value 3073 of three and the support for more ciphering types in the CipherSpec. 3075 Warning: The ability to send Version 2.0 client hello messages will be 3076 phased out with all due haste. Implementors should make every 3077 effort to move forward as quickly as possible. Version 3.0 3078 provides better mechanisms for moving to newer versions. 3080 The following cipher specifications are carryovers from SSL Version 3081 2.0. These are assumed to use RSA for key exchange and 3082 authentication. 3084 V2CipherSpec TLS_RC4_128_WITH_MD5 = { 0x01,0x00,0x80 }; 3085 V2CipherSpec TLS_RC4_128_EXPORT40_WITH_MD5 = { 0x02,0x00,0x80 }; 3086 V2CipherSpec TLS_RC2_CBC_128_CBC_WITH_MD5 = { 0x03,0x00,0x80 }; 3087 V2CipherSpec TLS_RC2_CBC_128_CBC_EXPORT40_WITH_MD5 3088 = { 0x04,0x00,0x80 }; 3089 V2CipherSpec TLS_IDEA_128_CBC_WITH_MD5 = { 0x05,0x00,0x80 }; 3090 V2CipherSpec TLS_DES_64_CBC_WITH_MD5 = { 0x06,0x00,0x40 }; 3091 V2CipherSpec TLS_DES_192_EDE3_CBC_WITH_MD5 = { 0x07,0x00,0xC0 }; 3093 Cipher specifications native to TLS can be included in Version 2.0 3094 client hello messages using the syntax below. Any V2CipherSpec 3095 element with its first byte equal to zero will be ignored by Version 3096 2.0 servers. Clients sending any of the above V2CipherSpecs should 3097 also include the TLS equivalent (see Appendix A.5): 3099 V2CipherSpec (see TLS name) = { 0x00, CipherSuite }; 3101 E.1. Version 2 client hello 3103 The Version 2.0 client hello message is presented below using this 3104 document's presentation model. The true definition is still assumed 3105 to be the SSL Version 2.0 specification. 3107 uint8 V2CipherSpec[3]; 3109 struct { 3110 uint8 msg_type; 3111 Version version; 3112 uint16 cipher_spec_length; 3113 uint16 session_id_length; 3114 uint16 challenge_length; 3115 V2CipherSpec cipher_specs[V2ClientHello.cipher_spec_length]; 3116 opaque session_id[V2ClientHello.session_id_length]; 3117 Random challenge; 3118 } V2ClientHello; 3120 msg_type 3121 This field, in conjunction with the version field, identifies a 3122 version 2 client hello message. The value should be one (1). 3124 version 3125 The highest version of the protocol supported by the client 3126 (equals ProtocolVersion.version, see Appendix A.1). 3128 cipher_spec_length 3129 This field is the total length of the field cipher_specs. It 3130 cannot be zero and must be a multiple of the V2CipherSpec length 3131 (3). 3133 session_id_length 3134 This field must have a value of either zero or 16. If zero, the 3135 client is creating a new session. If 16, the session_id field 3136 will contain the 16 bytes of session identification. 3138 challenge_length 3139 The length in bytes of the client's challenge to the server to 3140 authenticate itself. This value must be 32. 3142 cipher_specs 3143 This is a list of all CipherSpecs the client is willing and able 3144 to use. There must be at least one CipherSpec acceptable to the 3145 server. 3147 session_id 3148 If this field's length is not zero, it will contain the 3149 identification for a session that the client wishes to resume. 3151 challenge 3152 The client challenge to the server for the server to identify 3153 itself is a (nearly) arbitrary length random. The TLS server 3154 will right justify the challenge data to become the 3155 ClientHello.random data (padded with leading zeroes, if 3156 necessary), as specified in this protocol specification. If the 3157 length of the challenge is greater than 32 bytes, only the last 3158 32 bytes are used. It is legitimate (but not necessary) for a V3 3159 server to reject a V2 ClientHello that has fewer than 16 bytes 3160 of challenge data. 3162 Note: Requests to resume a TLS session should use a TLS client hello. 3164 E.2. Avoiding man-in-the-middle version rollback 3166 When TLS clients fall back to Version 2.0 compatibility mode, they 3167 should use special PKCS #1 block formatting. This is done so that 3168 TLS servers will reject Version 2.0 sessions with TLS-capable 3169 clients. 3171 When TLS clients are in Version 2.0 compatibility mode, they set the 3172 right-hand (least-significant) 8 random bytes of the PKCS padding 3173 (not including the terminal null of the padding) for the RSA 3174 encryption of the ENCRYPTED-KEY-DATA field of the CLIENT-MASTER-KEY 3175 to 0x03 (the other padding bytes are random). After decrypting the 3176 ENCRYPTED-KEY-DATA field, servers that support TLS should issue an 3177 error if these eight padding bytes are 0x03. Version 2.0 servers 3178 receiving blocks padded in this manner will proceed normally. 3180 Appendix F 3182 F. Security analysis 3184 The TLS protocol is designed to establish a secure connection 3185 between a client and a server communicating over an insecure 3186 channel. This document makes several traditional assumptions, 3187 including that attackers have substantial computational resources 3188 and cannot obtain secret information from sources outside the 3189 protocol. Attackers are assumed to have the ability to capture, 3190 modify, delete, replay, and otherwise tamper with messages sent over 3191 the communication channel. This appendix outlines how TLS has been 3192 designed to resist a variety of attacks. 3194 F.1. Handshake protocol 3196 The handshake protocol is responsible for selecting a CipherSpec and 3197 generating a Master Secret, which together comprise the primary 3198 cryptographic parameters associated with a secure session. The 3199 handshake protocol can also optionally authenticate parties who have 3200 certificates signed by a trusted certificate authority. 3202 F.1.1. Authentication and key exchange 3204 TLS supports three authentication modes: authentication of both 3205 parties, server authentication with an unauthenticated client, and 3206 total anonymity. Whenever the server is authenticated, the channel 3207 is secure against man-in-the-middle attacks, but completely 3208 anonymous sessions are inherently vulnerable to such attacks. 3209 Anonymous servers cannot authenticate clients. If the server is 3210 authenticated, its certificate message must provide a valid 3211 certificate chain leading to an acceptable certificate authority. 3212 Similarly, authenticated clients must supply an acceptable 3213 certificate to the server. Each party is responsible for verifying 3214 that the other's certificate is valid and has not expired or been 3215 revoked. 3217 The general goal of the key exchange process is to create a 3218 pre_master_secret known to the communicating parties and not to 3219 attackers. The pre_master_secret will be used to generate the 3220 master_secret (see Section 8.1). The master_secret is required to 3221 generate the certificate verify and finished messages, encryption 3222 keys, and MAC secrets (see Sections 7.4.8, 7.4.9 and 6.3). By 3223 sending a correct finished message, parties thus prove that they 3224 know the correct pre_master_secret. 3226 F.1.1.1. Anonymous key exchange 3228 Completely anonymous sessions can be established using RSA or 3229 Diffie-Hellman for key exchange. With anonymous RSA, the client 3230 encrypts a pre_master_secret with the server's uncertified public 3231 key extracted from the server key exchange message. The result is 3232 sent in a client key exchange message. Since eavesdroppers do not 3233 know the server's private key, it will be infeasible for them to 3234 decode the pre_master_secret. (Note that no anonymous RSA Cipher 3235 Suites are defined in this document). 3237 With Diffie-Hellman, the server's public parameters are contained in 3238 the server key exchange message and the client's are sent in the 3239 client key exchange message. Eavesdroppers who do not know the 3240 private values should not be able to find the Diffie-Hellman result 3241 (i.e. the pre_master_secret). 3243 Warning: Completely anonymous connections only provide protection 3244 against passive eavesdropping. Unless an independent 3245 tamper-proof channel is used to verify that the finished 3246 messages were not replaced by an attacker, server 3247 authentication is required in environments where active 3248 man-in-the-middle attacks are a concern. 3250 F.1.1.2. RSA key exchange and authentication 3252 With RSA, key exchange and server authentication are combined. The 3253 public key may be either contained in the server's certificate or 3254 may be a temporary RSA key sent in a server key exchange message. 3255 When temporary RSA keys are used, they are signed by the server's 3256 RSA or DSS certificate. The signature includes the current 3257 ClientHello.random, so old signatures and temporary keys cannot be 3258 replayed. Servers may use a single temporary RSA key for multiple 3259 negotiation sessions. 3261 Note: The temporary RSA key option is useful if servers need large 3262 certificates but must comply with government-imposed size limits 3263 on keys used for key exchange. 3265 After verifying the server's certificate, the client encrypts a 3266 pre_master_secret with the server's public key. By successfully 3267 decoding the pre_master_secret and producing a correct finished 3268 message, the server demonstrates that it knows the private key 3269 corresponding to the server certificate. 3271 When RSA is used for key exchange, clients are authenticated using 3272 the certificate verify message (see Section 7.4.8). The client signs 3273 a value derived from the master_secret and all preceding handshake 3274 messages. These handshake messages include the server certificate, 3275 which binds the signature to the server, and ServerHello.random, 3276 which binds the signature to the current handshake process. 3278 F.1.1.3. Diffie-Hellman key exchange with authentication 3280 When Diffie-Hellman key exchange is used, the server can either 3281 supply a certificate containing fixed Diffie-Hellman parameters or 3282 can use the server key exchange message to send a set of temporary 3283 Diffie-Hellman parameters signed with a DSS or RSA certificate. 3284 Temporary parameters are hashed with the hello.random values before 3285 signing to ensure that attackers do not replay old parameters. In 3286 either case, the client can verify the certificate or signature to 3287 ensure that the parameters belong to the server. 3289 If the client has a certificate containing fixed Diffie-Hellman 3290 parameters, its certificate contains the information required to 3291 complete the key exchange. Note that in this case the client and 3292 server will generate the same Diffie-Hellman result (i.e., 3293 pre_master_secret) every time they communicate. To prevent the 3294 pre_master_secret from staying in memory any longer than necessary, 3295 it should be converted into the master_secret as soon as possible. 3296 Client Diffie-Hellman parameters must be compatible with those 3297 supplied by the server for the key exchange to work. 3299 If the client has a standard DSS or RSA certificate or is 3300 unauthenticated, it sends a set of temporary parameters to the 3301 server in the client key exchange message, then optionally uses a 3302 certificate verify message to authenticate itself. 3304 F.1.2. Version rollback attacks 3306 Because TLS includes substantial improvements over SSL Version 2.0, 3307 attackers may try to make TLS-capable clients and servers fall back 3308 to Version 2.0. This attack can occur if (and only if) two 3309 TLS-capable parties use an SSL 2.0 handshake. 3311 Although the solution using non-random PKCS #1 block type 2 message 3312 padding is inelegant, it provides a reasonably secure way for 3313 Version 3.0 servers to detect the attack. This solution is not 3314 secure against attackers who can brute force the key and substitute 3315 a new ENCRYPTED-KEY-DATA message containing the same key (but with 3316 normal padding) before the application specified wait threshold has 3317 expired. Parties concerned about attacks of this scale should not be 3318 using 40-bit encryption keys anyway. Altering the padding of the 3319 least-significant 8 bytes of the PKCS padding does not impact 3320 security for the size of the signed hashes and RSA key lengths used 3321 in the protocol, since this is essentially equivalent to increasing 3322 the input block size by 8 bytes. 3324 F.1.3. Detecting attacks against the handshake protocol 3326 An attacker might try to influence the handshake exchange to make 3327 the parties select different encryption algorithms than they would 3328 normally choose. Because many implementations will support 40-bit 3329 exportable encryption and some may even support null encryption or 3330 MAC algorithms, this attack is of particular concern. 3332 For this attack, an attacker must actively change one or more 3333 handshake messages. If this occurs, the client and server will 3334 compute different values for the handshake message hashes. As a 3335 result, the parties will not accept each others' finished messages. 3336 Without the master_secret, the attacker cannot repair the finished 3337 messages, so the attack will be discovered. 3339 F.1.4. Resuming sessions 3341 When a connection is established by resuming a session, new 3342 ClientHello.random and ServerHello.random values are hashed with the 3343 session's master_secret. Provided that the master_secret has not 3344 been compromised and that the secure hash operations used to produce 3345 the encryption keys and MAC secrets are secure, the connection 3346 should be secure and effectively independent from previous 3347 connections. Attackers cannot use known encryption keys or MAC 3348 secrets to compromise the master_secret without breaking the secure 3349 hash operations (which use both SHA and MD5). 3351 Sessions cannot be resumed unless both the client and server agree. 3352 If either party suspects that the session may have been compromised, 3353 or that certificates may have expired or been revoked, it should 3354 force a full handshake. An upper limit of 24 hours is suggested for 3355 session ID lifetimes, since an attacker who obtains a master_secret 3356 may be able to impersonate the compromised party until the 3357 corresponding session ID is retired. Applications that may be run in 3358 relatively insecure environments should not write session IDs to 3359 stable storage. 3361 F.1.5. MD5 and SHA 3363 TLS uses hash functions very conservatively. Where possible, both 3364 MD5 and SHA are used in tandem to ensure that non-catastrophic flaws 3365 in one algorithm will not break the overall protocol. 3367 F.2. Protecting application data 3369 The master_secret is hashed with the ClientHello.random and 3370 ServerHello.random to produce unique data encryption keys and MAC 3371 secrets for each connection. 3373 Outgoing data is protected with a MAC before transmission. To 3374 prevent message replay or modification attacks, the MAC is computed 3375 from the MAC secret, the sequence number, the message length, the 3376 message contents, and two fixed character strings. The message type 3377 field is necessary to ensure that messages intended for one TLS 3378 Record Layer client are not redirected to another. The sequence 3379 number ensures that attempts to delete or reorder messages will be 3380 detected. Since sequence numbers are 64-bits long, they should never 3381 overflow. Messages from one party cannot be inserted into the 3382 other's output, since they use independent MAC secrets. Similarly, 3383 the server-write and client-write keys are independent so stream 3384 cipher keys are used only once. 3386 If an attacker does break an encryption key, all messages encrypted 3387 with it can be read. Similarly, compromise of a MAC key can make 3388 message modification attacks possible. Because MACs are also 3389 encrypted, message-alteration attacks generally require breaking the 3390 encryption algorithm as well as the MAC. 3392 Note: MAC secrets may be larger than encryption keys, so messages can 3393 remain tamper resistant even if encryption keys are broken. 3395 F.3. Final notes 3397 For TLS to be able to provide a secure connection, both the client 3398 and server systems, keys, and applications must be secure. In 3399 addition, the implementation must be free of security errors. 3401 The system is only as strong as the weakest key exchange and 3402 authentication algorithm supported, and only trustworthy 3403 cryptographic functions should be used. Short public keys, 40-bit 3404 bulk encryption keys, and anonymous servers should be used with 3405 great caution. Implementations and users must be careful when 3406 deciding which certificates and certificate authorities are 3407 acceptable; a dishonest certificate authority can do tremendous 3408 damage. 3410 Appendix G 3412 G. Patent Statement 3414 Some of the cryptographic algorithms proposed for use in this 3415 protocol have patent claims on them. In addition Netscape 3416 Communications Corporation has a patent claim on the Secure Sockets 3417 Layer (SSL) work that this standard is based on. The Internet 3418 Standards Process as defined in RFC 1310 requires a written 3419 statement from the Patent holder that a license will be made 3420 available to applicants under reasonable terms and conditions prior 3421 to approving a specification as a Proposed, Draft or Internet 3422 Standard. 3424 The Massachusetts Institute of Technology has granted RSA Data 3425 Security, Inc., exclusive sub-licensing rights to the following 3426 patent issued in the United States: 3428 Cryptographic Communications System and Method ("RSA"), No. 3429 4,405,829 3431 Netscape Communications Corporation has been issued the following 3432 patent in the United States: 3434 Secure Socket Layer Application Program Apparatus And Method 3435 ("SSL"), No. 5,657,390 3437 Netscape Communications has issued the following statement: 3439 Intellectual Property Rights 3441 Secure Sockets Layer 3443 The United States Patent and Trademark Office ("the PTO") 3444 recently issued U.S. Patent No. 5,657,390 ("the SSL Patent") to 3445 Netscape for inventions described as Secure Sockets Layers 3446 ("SSL"). The IETF is currently considering adopting SSL as a 3447 transport protocol with security features. Netscape encourages 3448 the royalty-free adoption and use of the SSL protocol upon the 3449 following terms and conditions: 3451 * If you already have a valid SSL Ref license today which 3452 includes source code from Netscape, an additional patent 3453 license under the SSL patent is not required. 3455 * If you don't have an SSL Ref license, you may have a royalty 3456 free license to build implementations covered by the SSL 3457 Patent Claims or the IETF TLS specification provided that 3458 you do not to assert any patent rights against Netscape or 3459 other companies for the implementation of SSL or the IETF 3460 TLS recommendation. 3462 What are "Patent Claims": 3464 Patent claims are claims in an issued foreign or domestic patent 3465 that: 3467 1) must be infringed in order to implement methods or build 3468 products according to the IETF TLS specification; or 3470 2) patent claims which require the elements of the SSL patent 3471 claims and/or their equivalents to be infringed. 3473 The Internet Society, Internet Architecture Board, Internet 3474 Engineering Steering Group and the Corporation for National Research 3475 Initiatives take no position on the validity or scope of the patents 3476 and patent applications, nor on the appropriateness of the terms of 3477 the assurance. The Internet Society and other groups mentioned above 3478 have not made any determination as to any other intellectual 3479 property rights which may apply to the practice of this standard. 3480 Any further consideration of these matters is the user's own 3481 responsibility. 3483 References 3485 [3DES] W. Tuchman, "Hellman Presents No Shortcut Solutions To DES," 3486 IEEE Spectrum, v. 16, n. 7, July 1979, pp40-41. 3488 [BLEI] Bleichenbacher D., "Chosen Ciphertext Attacks against 3489 Protocols Based on RSA Encryption Standard PKCS #1" in Advances in 3490 Cryptology -- CRYPTO'98, LNCS vol. 1462, pages: 1--12, 1998. 3492 [DES] ANSI X3.106, "American National Standard for Information 3493 Systems-Data Link Encryption," American National Standards 3494 Institute, 1983. 3496 [DH1] W. Diffie and M. E. Hellman, "New Directions in Cryptography," 3497 IEEE Transactions on Information Theory, V. IT-22, n. 6, Jun 1977, 3498 pp. 74-84. 3500 [DSS] NIST FIPS PUB 186, "Digital Signature Standard," National 3501 Institute of Standards and Technology, U.S. Department of Commerce, 3502 May 18, 1994. 3504 [FTP] J. Postel and J. Reynolds, RFC 959: File Transfer Protocol, 3505 October 1985. 3507 [HTTP] T. Berners-Lee, R. Fielding, H. Frystyk, Hypertext Transfer 3508 Protocol -- HTTP/1.0, October, 1995. 3510 [HMAC] H. Krawczyk, M. Bellare, and R. Canetti, RFC 2104, HMAC: 3511 Keyed-Hashing for Message Authentication, February, 1997. 3513 [IDEA] X. Lai, "On the Design and Security of Block Ciphers," ETH 3514 Series in Information Processing, v. 1, Konstanz: Hartung-Gorre 3515 Verlag, 1992. 3517 [MD2] R. Rivest. RFC 1319: The MD2 Message Digest Algorithm. April 3518 1992. 3520 [MD5] R. Rivest. RFC 1321: The MD5 Message Digest Algorithm. April 3521 1992. 3523 [PKCS1] RSA Laboratories, "PKCS #1: RSA Encryption Standard," 3524 version 1.5, November 1993. 3526 [PKCS6] RSA Laboratories, "PKCS #6: RSA Extended Certificate Syntax 3527 Standard," version 1.5, November 1993. 3529 [PKCS7] RSA Laboratories, "PKCS #7: RSA Cryptographic Message Syntax 3530 Standard," version 1.5, November 1993. 3532 [PKIX] R. Housley, W. Ford, W. Polk, D. Solo, Internet Public Key 3533 Infrastructure: Part I: X.509 Certificate and CRL Profile, 3534 , October 1997. 3536 [RC2] R. Rivest, A Description of the RC2(r) Encryption Algorithm 3537 3539 [RC4] R. Thayer and K. Kaukonen, A Stream Cipher Encryption 3540 Algorithm, , July 1997. 3542 [RSA] R. Rivest, A. Shamir, and L. M. Adleman, "A Method for 3543 Obtaining Digital Signatures and Public-Key Cryptosystems," 3544 Communications of the ACM, v. 21, n. 2, Feb 1978, pp. 120-126. 3546 [RSADSI] Contact RSA Data Security, Inc., Tel: 415-595-8782 [SCH] B. 3547 Schneier. Applied Cryptography: Protocols, Algorithms, and Source 3548 Code in C, Published by John Wiley & Sons, Inc. 1994. 3550 [SHA] NIST FIPS PUB 180-1, "Secure Hash Standard," National 3551 Institute of Standards and Technology, U.S. Department of Commerce, 3552 DRAFT, May 31, 1994. 3554 [SSL2] Hickman, Kipp, "The SSL Protocol", Netscape Communications 3555 Corp., Feb 9, 1995. 3557 [SSL3] A. Frier, P. Karlton, and P. Kocher, "The SSL 3.0 Protocol", 3558 Netscape Communications Corp., Nov 18, 1996. 3560 [TCP] ISI for DARPA, RFC 793: Transport Control Protocol, September 3561 1981. 3563 [TEL] J. Postel and J. Reynolds, RFC 854/5, May, 1993. 3565 [X509] CCITT. Recommendation X.509: "The Directory - Authentication 3566 Framework". 1988. 3568 [XDR] R. Srinivansan, Sun Microsystems, RFC-1832: XDR: External Data 3569 Representation Standard, August 1995. 3571 Credits 3573 Working Group Chair 3575 Win Treese 3576 Open Market 3577 treese@openmarket.com 3579 Editors 3581 Christopher Allen Tim Dierks 3582 Certicom Certicom 3583 callen@certicom.com tdierks@certicom.com 3585 Authors 3587 Tim Dierks Philip L. Karlton 3588 Certicom Netscape Communications 3589 tdierks@certicom.com 3591 Alan O. Freier Paul C. Kocher 3592 Netscape Communications Independent Consultant 3593 freier@netscape.com pck@netcom.com 3595 Other contributors 3597 Martin Abadi Robert Relyea 3598 Digital Equipment Corporation Netscape Communications 3599 ma@pa.dec.com relyea@netscape.com 3601 Ran Canetti Jim Roskind 3602 IBM Watson Research Center Netscape Communications 3603 canetti@watson.ibm.com jar@netscape.com 3605 Taher Elgamal Micheal J. Sabin, Ph. D. 3606 Securify Consulting Engineer 3607 taher@pacbell.net msabin@netcom.com 3609 Anil R. Gangolli Dan Simon 3610 Structured Arts Computing Corp. Microsoft 3611 gangolli@structuredarts.com dansimon@microsoft.com 3613 Kipp E.B. Hickman Tom Weinstein 3614 Netscape Communications Netscape Communications 3615 kipp@netscape.com tomw@netscape.com 3617 Hugo Krawczyk 3618 IBM Watson Research Center 3619 hugo@watson.ibm.com 3621 Comments 3623 The discussion list for the IETF TLS working group is located at the 3624 e-mail address . Information on the 3625 group and information on how to subscribe to the list is at 3626 . 3628 Archives of the list can be found at: 3629