idnits 2.17.1 draft-ietf-tls-protocol-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-25) 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. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 603 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 (March 6, 1997) is 9912 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) == Missing Reference: 'RC4' is mentioned on line 147, but not defined -- Looks like a reference, but probably isn't: '0' on line 260 -- Looks like a reference, but probably isn't: '1' on line 260 -- Looks like a reference, but probably isn't: '3' on line 2953 -- Looks like a reference, but probably isn't: '9' on line 296 -- Looks like a reference, but probably isn't: '2' on line 2306 -- Looks like a reference, but probably isn't: '4' on line 330 -- Looks like a reference, but probably isn't: '8' on line 331 -- Looks like a reference, but probably isn't: '10' on line 426 -- Looks like a reference, but probably isn't: '20' on line 2422 -- Looks like a reference, but probably isn't: '48' on line 2531 -- Looks like a reference, but probably isn't: '32' on line 2533 == Missing Reference: 'HMAC' is mentioned on line 672, but not defined == Missing Reference: 'ChangeCipherSpec' is mentioned on line 1401, but not defined -- Looks like a reference, but probably isn't: '28' on line 2301 -- Looks like a reference, but probably isn't: '16' on line 2421 -- Looks like a reference, but probably isn't: '46' on line 2398 == Missing Reference: 'IP' is mentioned on line 2170, but not defined == Missing Reference: 'SSL-2' is mentioned on line 2915, but not defined == Unused Reference: 'DH1' is defined on line 3303, but no explicit reference was found in the text == Unused Reference: 'FTP' is defined on line 3318, but no explicit reference was found in the text == Unused Reference: 'HTTP' is defined on line 3321, but no explicit reference was found in the text == Unused Reference: 'KRAW' is defined on line 3328, but no explicit reference was found in the text == Unused Reference: 'MD2' is defined on line 3331, but no explicit reference was found in the text == Unused Reference: 'TEL' is defined on line 3361, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'SSL3' -- Possible downref: Non-RFC (?) normative reference: ref. 'DH1' -- Possible downref: Non-RFC (?) normative reference: ref. '3DES' -- Possible downref: Non-RFC (?) normative reference: ref. 'DES' -- Possible downref: Non-RFC (?) normative reference: ref. 'DSS' -- Possible downref: Non-RFC (?) normative reference: ref. 'HTTP' -- Possible downref: Non-RFC (?) normative reference: ref. 'IDEA' -- Possible downref: Non-RFC (?) normative reference: ref. 'KRAW' ** 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. 'RSA' -- Possible downref: Non-RFC (?) normative reference: ref. 'RSADSI' -- Possible downref: Non-RFC (?) normative reference: ref. 'SHA' ** 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: 13 errors (**), 0 flaws (~~), 13 warnings (==), 32 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Transport Layer Security Working Group Tim Dierks 2 INTERNET-DRAFT Consensus Development 4 Christopher Allen 5 Consensus Development 7 Expires August 31, 1997 March 6, 1997 9 The TLS Protocol 10 Version 1.0 12 14 Status of this memo 16 This document is an Internet-Draft. Internet-Drafts are working 17 documents of the Internet Engineering Task Force (IETF), its areas, 18 and its working groups. Note that other groups may also distribute 19 working documents as Internet-Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six 22 months and may be updated, replaced, or made obsolete by other 23 documents at any time. It is inappropriate to use Internet-Drafts as 24 reference material or to cite them other than as work in progress. 26 To learn the current status of any Internet-Draft, please check the 27 1id-abstracts.txt listing contained in the Internet Drafts Shadow 28 Directories on ds.internic.net (US East Coast), nic.nordu.net 29 (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific 30 Rim). 32 Abstract 34 This document specifies Version 1.0 of the Transport Layer Security 35 (TLS) protocol, which is at this stage is strictly based on the 36 Secure Sockets Layer (SSL) version 3.0 protocol, and is to serve as 37 a basis for future discussions. The TLS protocol provides 38 communications privacy over the Internet. The protocol allows 39 client/server applications to communicate in a way that is designed 40 to prevent eavesdropping, tampering, or message forgery. 42 Table of Contents 44 Status of this memo 1 45 Abstract 1 46 Table of Contents 2 47 1. Introduction 3 48 2. Goals 4 49 3. Goals of this document 5 50 4. Presentation language 5 51 4.1. Basic block size 6 52 4.2. Miscellaneous 6 53 4.3. Vectors 6 54 4.4. Numbers 7 55 4.5. Enumerateds 7 56 4.6. Constructed types 8 57 4.6.1. Variants 8 58 4.7. Cryptographic attributes 9 59 4.8. Constants 10 60 5. The TLS Record Protocol 11 61 5.1. Connection states 11 62 5.2. HMAC and the pseudorandom function 14 63 5.3. Record layer 14 64 5.3.1. Fragmentation 14 65 5.3.2. Record compression and decompression 15 66 5.3.3. Record payload protection 16 67 5.3.3.1. Null or standard stream cipher 17 68 5.3.3.2. CBC block cipher 17 69 5.4. Key calculation 18 70 5.4.1. Export key generation example 20 71 6. The TLS Handshake Protocol 20 72 6.1. Change cipher spec protocol 21 73 6.2. Alert protocol 22 74 6.2.1. Closure alerts 22 75 6.2.2. Error alerts 23 76 6.3. Handshake Protocol overview 25 77 6.4. Handshake protocol 28 78 6.4.1. Hello messages 29 79 6.4.1.1. Hello request 29 80 6.4.1.2. Client hello 29 81 6.4.1.3. Server hello 32 82 6.4.2. Server certificate 33 83 6.4.3. Server key exchange message 34 84 6.4.4. Certificate request 36 85 6.4.5. Server hello done 37 86 6.4.6. Client certificate 38 87 6.4.7. Client key exchange message 38 88 6.4.7.1. RSA encrypted premaster secret message 39 89 6.4.7.2. Client Diffie-Hellman public value 39 90 6.4.8. Certificate verify 40 91 6.4.9. Finished 40 92 7. Cryptographic computations 41 93 7.1. Computing the master secret 42 94 7.1.1. RSA 42 95 7.1.2. Diffie-Hellman 42 96 8. Application data protocol 42 97 A. Protocol constant values 42 98 A.1. Reserved port assignments 43 99 A.2. Record layer 43 100 A.3. Change cipher specs message 44 101 A.4. Alert messages 44 102 A.5. Handshake protocol 45 103 A.5.1. Hello messages 45 104 A.5.2. Server authentication and key exchange messages 46 105 A.5.3. Client authentication and key exchange messages 47 106 A.5.4. Handshake finalization message 47 107 A.6. The CipherSuite 48 108 A.7. The Security Parameters 49 109 B. Glossary 50 110 C. CipherSuite definitions 53 111 D. Implementation Notes 55 112 D.1. Temporary RSA keys 55 113 D.2. Random Number Generation and Seeding 55 114 D.3. Certificates and authentication 56 115 D.4. CipherSuites 56 116 E. Backward Compatibility With SSL 56 117 E.1. Version 2 client hello 58 118 E.2. Avoiding man-in-the-middle version rollback 59 119 F. Security analysis 59 120 F.1. Handshake protocol 59 121 F.1.1. Authentication and key exchange 60 122 F.1.1.1. Anonymous key exchange 60 123 F.1.1.2. RSA key exchange and authentication 61 124 F.1.1.3. Diffie-Hellman key exchange with authentication 61 125 F.1.2. Version rollback attacks 62 126 F.1.3. Detecting attacks against the handshake protocol 62 127 F.1.4. Resuming sessions 62 128 F.1.5. MD5 and SHA 63 129 F.2. Protecting application data 63 130 F.3. Final notes 63 131 G. Patent Statement 64 132 References 64 133 Credits 66 134 Comments 67 136 1. Introduction 138 The primary goal of the TLS Protocol is to provide privacy and 139 reliability between two communicating applications. The protocol is 140 composed of two layers: the TLS Record Protocol and the TLS 141 Handshake Protocol. At the lowest level, layered on top of some 142 reliable transport protocol (e.g., TCP[TCP]), is the TLS Record 143 Protocol. The TLS Record Protocol provides connection security that 144 has two basic properties: 146 - The connection is private. Symmetric cryptography is used for 147 data encryption (e.g., DES[DES], RC4[RC4], etc.) The keys for 148 this symmetric encryption are generated uniquely for each 149 connection and are based on a secret negotiated by another 150 protocol (such as the TLS Handshake Protocol). The Record 151 | Protocol can also be used without encryption. 153 - The connection is reliable. Message transport includes a message 154 integrity check using a keyed MAC. Secure hash functions (e.g., 155 SHA, MD5, etc.) are used for MAC computations. The Record 156 Protocol can operate without a MAC, but is generally only used 157 in this mode while another protocol is using the Record Protocol 158 as a transport for negotiating security parameters. 160 The TLS Record Protocol is used for encapsulation of various higher 161 level protocols. One such encapsulated protocol, the TLS Handshake 162 Protocol, allows the server and client to authenticate each other 163 and to negotiate an encryption algorithm and cryptographic keys 164 before the application protocol transmits or receives its first byte 165 of data. The TLS Handshake Protocol provides connection security 166 that has three basic properties: 168 - The peer's identity can be authenticated using asymmetric, or 169 public key, cryptography (e.g., RSA[RSA], DSS[DSS], etc.). This 170 authentication can be made optional, but is generally required 171 for at least one of the peers. 173 - The negotiation of a shared secret is secure: the negotiated 174 | secret is unavailable to eavesdroppers, and for any 175 | authenticated connection the secret cannot be obtained, even by 176 | an attacker who can place himself in the middle of the 177 | connection. 179 - The negotiation is reliable: no attacker can modify the 180 | negotiation communication without being detected by the parties 181 | to the communication. 183 One advantage of TLS is that it is application protocol independent. 184 | Higher level protocols can layer on top of the TLS Protocol 185 transparently. 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 Note: It is not the case that all instances of TLS (even in the same 200 application domain) will be able to successfully connect. For 201 instance, if the server supports a particular hardware token, 202 and the client does not have access to such a token, then the 203 | connection will not succeed. There is no required set of ciphers 204 | for minimal compliance, so some implementations may be unable to 205 | communicate. 207 3. Extensibility: TLS seeks to provide a framework into which new 208 public key and bulk encryption methods can be incorporated as 209 necessary. This will also accomplish two sub-goals: to prevent 210 the need to create a new protocol (and risking the introduction 211 of possible new weaknesses) and to avoid the need to implement 212 an entire new security library. 214 4. Relative efficiency: Cryptographic operations tend to be highly 215 CPU intensive, particularly public key operations. For this 216 reason, the TLS protocol has incorporated an optional session 217 caching scheme to reduce the number of connections that need to 218 be established from scratch. Additionally, care has been taken 219 to reduce network activity. 221 3. Goals of this document 223 | This document and the TLS protocol itself are based on the SSL 3.0 224 | Protocol Specification as published by Netscape. The differences 225 | between this protocol and SSL 3.0 are not dramatic, but they are 226 | significant enough that TLS 1.0 and SSL 3.0 do not interoperate 227 | (although TLS 1.0 does incorporate a mechanism by which a TLS 228 | implementation can back down to SSL 3.0). This document is intended 229 | primarily for readers who will be implementing the protocol and 230 | those doing cryptographic analysis of it. The spec has been written 231 | with this in mind, and it is intended to reflect the needs of those 232 | two groups. For that reason, many of the algorithm-dependent data 233 | structures and rules are included in the body of the text (as 234 | opposed to in an Appendix), providing easier access to them. 236 This document is not intended to supply any details of service 237 definition nor interface definition, although it does cover select 238 areas of policy as they are required for the maintenance of solid 239 security. 241 4. Presentation language 243 This document deals with the formatting of data in an external 244 representation. The following very basic and somewhat casually 245 defined presentation syntax will be used. The syntax draws from 246 several sources in its structure. Although it resembles the 247 programming language "C" in its syntax and XDR [XDR] in both its 248 syntax and intent, it would be risky to draw too many parallels. The 249 purpose of this presentation language is to document TLS only, not 250 to have general application beyond that particular goal. 252 4.1. Basic block size 254 The representation of all data items is explicitly specified. The 255 basic data block size is one byte (i.e. 8 bits). Multiple byte data 256 items are concatenations of bytes, from left to right, from top to 257 bottom. From the bytestream a multi-byte item (a numeric in the 258 example) is formed (using C notation) by: 260 value = (byte[0] << 8*(n-1)) | (byte[1] << 8*(n-2)) | 261 ... | byte[n-1]; 263 This byte ordering for multi-byte values is the commonplace network 264 byte order or big endian format. 266 4.2. Miscellaneous 268 Comments begin with "/*" and end with "*/". 270 Optional components are denoted by enclosing them in "[[ ]]" double 271 brackets. 273 Single byte entities containing uninterpreted data are of type 274 opaque. 276 4.3. Vectors 278 A vector (single dimensioned array) is a stream of homogeneous data 279 elements. The size of the vector may be specified at documentation 280 time or left unspecified until runtime. In either case the length 281 declares the number of bytes, not the number of elements, in the 282 vector. The syntax for specifying a new type T' that is a fixed 283 length vector of type T is 285 T T'[n]; 287 Here T' occupies n bytes in the data stream, where n is a multiple 288 of the size of T. The length of the vector is not included in the 289 encoded stream. 291 In the following example, Datum is defined to be three consecutive 292 bytes that the protocol does not interpret, while Data is three 293 consecutive Datum, consuming a total of nine bytes. 295 opaque Datum[3]; /* three uninterpreted bytes */ 296 Datum Data[9]; /* 3 consecutive 3 byte vectors */ 298 Variable length vectors are defined by specifying a subrange of 299 legal lengths, inclusively, using the notation . 300 When encoded, the actual length precedes the vector's contents in 301 the byte stream. The length will be in the form of a number 302 consuming as many bytes as required to hold the vector's specified 303 maximum (ceiling) length. A variable length vector with an actual 304 length field of zero is referred to as an empty vector. 306 T T'; 308 In the following example, mandatory is a vector that must contain 309 between 300 and 400 bytes of type opaque. It can never be empty. The 310 actual length field consumes two bytes, a uint16, sufficient to 311 represent the value 400 (see Section 4.4). On the other hand, longer 312 can represent up to 800 bytes of data, or 400 uint16 elements, and 313 it may be empty. Its encoding will include a two byte actual length 314 field prepended to the vector. 316 opaque mandatory<300..400>; 317 /* length field is 2 bytes, cannot be empty */ 318 uint16 longer<0..800>; 319 /* zero to 400 16-bit unsigned integers */ 321 4.4. Numbers 323 The basic numeric data type is an unsigned byte (uint8). All larger 324 numeric data types are formed from fixed length series of bytes 325 concatenated as described in Section 4.1 and are also unsigned. The 326 following numeric types are predefined. 328 uint8 uint16[2]; 329 uint8 uint24[3]; 330 uint8 uint32[4]; 331 uint8 uint64[8]; 333 | All values, here and elsewhere in the specification, are stored in 334 | "network" or "big-endian" order; the uint32 represented by the hex 335 | bytes 01 02 03 04 is equivalent to the decimal value 16909060. 337 4.5. Enumerateds 339 An additional sparse data type is available called enum. A field of 340 type enum can only assume the values declared in the definition. 341 Each definition is a different type. Only enumerateds of the same 342 type may be assigned or compared. Every element of an enumerated 343 must be assigned a value, as demonstrated in the following example. 344 Since the elements of the enumerated are not ordered, they can be 345 assigned any unique value, in any order. 347 enum { e1(v1), e2(v2), ... , en(vn), [[(n)]] } Te; 349 Enumerateds occupy as much space in the byte stream as would its 350 maximal defined ordinal value. The following definition would cause 351 one byte to be used to carry fields of type Color. 353 enum { red(3), blue(5), white(7) } Color; 355 One may optionally specify a value without its associated tag to 356 force the width definition without defining a superfluous element. 357 In the following example, Taste will consume two bytes in the data 358 stream but can only assume the values 1, 2 or 4. 360 enum { sweet(1), sour(2), bitter(4), (32000) } Taste; 362 The names of the elements of an enumeration are scoped within the 363 defined type. In the first example, a fully qualified reference to 364 the second element of the enumeration would be Color.blue. Such 365 qualification is not required if the target of the assignment is 366 well specified. 368 Color color = Color.blue; /* overspecified, legal */ 369 Color color = blue; /* correct, type implicit */ 371 For enumerateds that are never converted to external representation, 372 the numerical information may be omitted. 374 enum { low, medium, high } Amount; 376 4.6. Constructed types 378 Structure types may be constructed from primitive types for 379 convenience. Each specification declares a new, unique type. The 380 syntax for definition is much like that of C. 382 struct { 383 T1 f1; 384 T2 f2; 385 ... 386 Tn fn; 387 } [[T]]; 389 The fields within a structure may be qualified using the type's name 390 using a syntax much like that available for enumerateds. For 391 example, T.f2 refers to the second field of the previous 392 declaration. Structure definitions may be embedded. 394 4.6.1. Variants 396 Defined structures may have variants based on some knowledge that is 397 available within the environment. The selector must be an enumerated 398 type that defines the possible variants the structure defines. There 399 must be a case arm for every element of the enumeration declared in 400 the select. The body of the variant structure may be given a label 401 for reference. The mechanism by which the variant is selected at 402 runtime is not prescribed by the presentation language. 404 struct { 405 T1 f1; 406 T2 f2; 407 .... 408 Tn fn; 409 select (E) { 410 case e1: Te1; 411 case e2: Te2; 412 .... 413 case en: Ten; 414 } [[fv]]; 415 } [[Tv]]; 417 For example: 419 enum { apple, orange } VariantTag; 420 struct { 421 uint16 number; 422 opaque string<0..10>; /* variable length */ 423 } V1; 424 struct { 425 uint32 number; 426 opaque string[10]; /* fixed length */ 427 } V2; 428 struct { 429 select (VariantTag) { /* value of selector is implicit */ 430 case apple: V1; /* VariantBody, tag = apple */ 431 case orange: V2; /* VariantBody, tag = orange */ 432 } variant_body; /* optional label on variant */ 433 } VariantRecord; 435 Variant structures may be qualified (narrowed) by specifying a value 436 for the selector prior to the type. For example, a 438 orange VariantRecord 440 is a narrowed type of a VariantRecord containing a variant_body of 441 type V2. 443 4.7. Cryptographic attributes 445 The four cryptographic operations digital signing, stream cipher 446 encryption, block cipher encryption, and public key encryption are 447 designated digitally-signed, stream-ciphered, block-ciphered, and 448 public-key-encrypted, respectively. A field's cryptographic 449 processing is specified by prepending an appropriate key word 450 designation before the field's type specification. Cryptographic 451 keys are implied by the current session state (see Section 5.1). 453 In digital signing, one-way hash functions are used as input for a 454 signing algorithm. In RSA signing, a 36-byte structure of two hashes 455 (one SHA and one MD5) is signed (encrypted with the private key). In 456 DSS, the 20 bytes of the SHA hash are run directly through the 457 Digital Signing Algorithm with no additional hashing. A 458 digitally-signed element is encoded as an opaque vector <0..2^16-1>, 459 where the length is specified by the signing algorithm and key. 461 In stream cipher encryption, the plaintext is exclusive-ORed with an 462 identical amount of output generated from a cryptographically-secure 463 keyed pseudorandom number generator. 465 In block cipher encryption, every block of plaintext encrypts to a 466 block of ciphertext. All block cipher encryption is done in CBC 467 (Cipher Block Chaining) mode, and all items which are block-ciphered 468 will be an exact multiple of the cipher block length. 470 In public key encryption, a public key algorithm is used to encrypt 471 data in such a way that it can be decrypted only with the matching 472 private key. A public-key-encrypted element is encoded as an opaque 473 vector <0..2^16-1>, where the length is specified by the signing 474 algorithm and key. 476 In the following example: 478 stream-ciphered struct { 479 uint8 field1; 480 uint8 field2; 481 digitally-signed opaque hash[20]; 482 } UserType; 484 The contents of hash are used as input for the signing algorithm, 485 then the entire structure is encrypted with a stream cipher. The 486 length of this structure, in bytes would be equal to 2 bytes for 487 field1 and field2, plus two bytes for the length of the signature, 488 plus the length of the output of the signing algorithm. This is 489 known due to the fact that the algorithm and key used for the 490 signing are known prior to encoding or decoding this structure. 492 4.8. Constants 494 Typed constants can be defined for purposes of specification by 495 declaring a symbol of the desired type and assigning values to it. 496 Under-specified types (opaque, variable length vectors, and 497 structures that contain opaque) cannot be assigned values. No fields 498 of a multi-element structure or vector may be elided. 500 For example, 502 struct { 503 uint8 f1; 504 uint8 f2; 505 } Example1; 507 Example1 ex1 = {1, 4}; /* assigns f1 = 1, f2 = 4 */ 509 5. The TLS Record Protocol 511 The TLS Record Protocol is a layered protocol. At each layer, 512 messages may include fields for length, description, and content. 513 The Record Protocol takes messages to be transmitted, fragments the 514 data into manageable blocks, optionally compresses the data, applies 515 a MAC, encrypts, and transmits the result. Received data is 516 decrypted, verified, decompressed, and reassembled, then delivered 517 to higher level clients. 519 | Four record protocol clients are described in this document: the 520 | handshake protocol, the alert protocol, the change cipher spec 521 | protocol, and the application data protocol. In order to allow 522 | extension of the TLS protocol, additional record types can be 523 | supported by the record protocol. Any new record types should 524 | allocate type values immediately beyond the ContentType values for 525 | the four record types described here (see Appendix A.2). If a TLS 526 | implementation receives a record type it does not understand, it 527 | should just ignore it. Any protocol designed for use over TLS must 528 | be carefully designed to deal with all possible attacks against it. 530 5.1. Connection states 532 A TLS connection state is the operating environment of the TLS 533 Record Protocol. It specifies a compression algorithm, encryption 534 algorithm, and MAC algorithm. In addition, the parameters for these 535 algorithms are known: the MAC secret and the bulk encryption keys 536 and IVs for the connection in both the read and the write 537 directions. Logically, there are always four connection states 538 outstanding: the current read and write states, and the pending read 539 and write states. All records are processed under the current read 540 and write states. The security parameters for the pending states can 541 be set by the TLS Handshake Protocol, and the Handshake Protocol can 542 selectively make either of the pending states current, in which case 543 the appropriate current state is disposed of and replaced with the 544 pending state; the pending state is then reinitialized to an empty 545 state. It is illegal to make a state which has not been initialized 546 with security parameters a current state (although those security 547 parameters may specify that no compression, encryption or MAC 548 algorithm is to be used). The initial current state always specifies 549 that no encryption, compression, or MAC will be used. 551 The security parameters for a TLS Connection read and write state 552 are set by providing the following values: 554 connection end 555 Whether this entity is considered the "client" or the "server" 556 in this connection. 558 bulk encryption algorithm 559 An algorithm to be used for bulk encryption. This specification 560 includes the key size of this algorithm, how much of that key is 561 secret, whether it is a block or stream cipher, the block size 562 of the cipher (if appropriate), and whether it is considered an 563 "export" cipher. 565 MAC algorithm 566 An algorithm to be used for message authentication. This 567 | specification includes the size of the hash which is returned by 568 | the MAC algorithm. 570 compression algorithm 571 An algorithm to be used for data compression. This specification 572 must include all information the algorithm requires to do 573 compression. 575 master secret 576 A 48 byte secret shared between the two peers in the connection. 578 client random 579 A 32 byte value provided by the client. 581 server random 582 A 32 byte value provided by the server. 584 These parameters are defined in the presentation language as: 586 enum { server, client } ConnectionEnd; 588 enum { null, rc4, rc2, des, 3des, des40 } BulkCipherAlgorithm; 590 enum { stream, block } CipherType; 592 enum { true, false } IsExportable; 594 enum { null, md5, sha } MACAlgorithm; 596 enum { null(0), (255) } CompressionMethod; 598 /* The algorithms specified in CompressionMethod, 599 BulkCipherAlgorithm, and MACAlgorithm may be added to. */ 601 struct { 602 ConnectionEnd entity; 603 BulkCipherAlgorithm bulk_cipher_algorithm; 604 CipherType cipher_type; 605 uint8 key_size; 606 uint8 key_material_length; 607 IsExportable is_exportable; 608 MACAlgorithm mac_algorithm; 609 uint8 hash_size; 610 CompressionMethod compression_algorithm; 611 opaque master_secret[48]; 612 opaque client_random[32]; 613 opaque server_random[32]; 614 } SecurityParameters; 616 The record layer will use the security parameters to generate the 617 following six items: 619 client write MAC secret 620 server write MAC secret 621 client write key 622 server write key 623 client write IV (for block ciphers only) 624 server write IV (for block ciphers only) 626 The client write parameters are used by the server when receiving 627 and processing records and vice-versa. The algorithm used for 628 generating these items from the security parameters is described in 629 section 5.4. 631 Once the security parameters have been set and the keys have been 632 generated, the connection states can be instantiated by making them 633 the current states. These current states must be updated for each 634 record processed. Each connection state includes the following 635 elements: 637 compression state 638 The current state of the compression algorithm. 640 cipher state 641 The current state of the encryption algorithm. This will consist 642 of the scheduled key for that connection. In addition, for block 643 | ciphers running in CBC mode, this will initially contain the IV 644 | for that connection state and be updated to contain the 645 | ciphertext of the last block encrypted or decrypted as records 646 | are processed. For block ciphers in other modes, whatever state 647 | is necessary to sustain encryption or decryption must be 648 | maintained. For stream ciphers, this will contain whatever the 649 | necessary state information is to allow the stream to continue 650 | to encrypt or decrypt data. 652 MAC secret 653 The MAC secret for this connection as generated above. 655 sequence number 656 Each connection state contains a sequence number, which is 657 maintained seperately for read and write states. The sequence 658 number must be set to zero whenever a connection state is made 659 the active state. Sequence numbers are of type uint64 and may 660 not exceed 2^64-1. A sequence number is incremented after each 661 record: specifically, the first record which is transmitted 662 under a particular connection state should use sequence number 663 0. 665 5.2. HMAC and the pseudorandom function 667 | A number of operations in the TLS record and handshake layer 668 | required a keyed MAC; this is a secure digest of some data protected 669 | by a secret. Forging the MAC is infeasible without knowledge of the 670 | MAC secret. Finding two data messages which have the same MAC is 671 | also cryptographically infeasible. The construction we use for this 672 | operation is known as HMAC, described in [HMAC]. 674 | HMAC can be used with a variety of different hash algorithms. TLS 675 | uses it with two different algorithms: MD5 and SHA-1, denoting these 676 | as HMAC_MD5(secret, data) and HMAC_SHA(secret, data). In order to 677 | extend the security even further, an additional construction is 678 | defined which uses both MD5 and SHA-1: HMAC_mix(secret, data) = 679 | HMAC_MD5(secret, HMAC_SHA(secret, data)). This provides some 680 | protection against either of the algorithms being completely broken. 682 | In addition, TLS needs the ability to generate a chunk of random 683 | data of arbitrary length from a secret and a seed. To do this, a 684 | pseudorandom function (PRF) is defined. This function generates data 685 | by repeatedly applying HMAC_mix to the secret and seed, generating 686 | 16 bytes at a time. 688 | PRF(secret, seed) = HMAC_mix(secret, 'A' + seed) + 690 | HMAC_mix(secret, 'BB' + seed) + 692 | HMAC_mix(secret, 'CCC' + seed) + ... 694 | Where + indicates concatenation 696 | Where each iteration of PRF generates 16 bytes of output and 697 | consists of the HMAC_mix of the secret and the seed, where the seed 698 | is varied by prepending a string of bytes, where the first iteration 699 | uses a one byte string with the single value 'A' (0x40), the second 700 | uses a two byte string containing the value 'B' (0x41) twice, and so 701 | on. This can be repeated to generate up to 26 16-byte blocks, which 702 | is more than TLS ever requires. 704 5.3. Record layer 706 The TLS Record Layer receives uninterpreted data from higher layers 707 in non-empty blocks of arbitrary size. 709 5.3.1. Fragmentation 711 The record layer fragments information blocks into TLSPlaintext 712 records of 2^14 bytes or less. Client message boundaries are not 713 preserved in the record layer (i.e., multiple client messages of the 714 same ContentType may be coalesced into a single TLSPlaintext record, 715 or may be fragmented across several records). 717 struct { 718 uint8 major, minor; 719 } ProtocolVersion; 721 enum { 722 change_cipher_spec(20), alert(21), handshake(22), 723 application_data(23), (255) 724 } ContentType; 726 struct { 727 ContentType type; 728 ProtocolVersion version; 729 uint16 length; 730 opaque fragment[TLSPlaintext.length]; 731 } TLSPlaintext; 733 type 734 The higher level protocol used to process the enclosed fragment. 736 version 737 The version of the protocol being employed. This document 738 | describes TLS Version 1.0, which uses the version { 3, 1 }. The 739 | version value 3.1 is historical: TLS version 1.0 is a minor 740 | modification to the SSL 3.0 protocol, which bears the version 741 | value 3.0. (See Appendix A.1.1). 743 length 744 The length (in bytes) of the following TLSPlaintext.fragment. 745 The length should not exceed 2^14. 747 fragment 748 The application data. This data is transparent and treated as an 749 independent block to be dealt with by the higher level protocol 750 specified by the type field. 752 Note: Data of different TLS Record layer content types may be 753 interleaved. Application data is generally of lower precedence 754 for transmission than other content types. 756 5.3.2. Record compression and decompression 758 All records are compressed using the compression algorithm defined 759 in the current session state. There is always an active compression 760 algorithm; however, initially it is defined as 761 CompressionMethod.null. The compression algorithm translates a 762 TLSPlaintext structure into a TLSCompressed structure. Compression 763 functions are initialized with default state information whenever a 764 connection state is made active. 766 Compression must be lossless and may not increase the content length 767 by more than 1024 bytes. If the decompression function encounters a 768 TLSCompressed.fragment that would decompress to a length in excess 769 of 2^14 bytes, it should report a fatal decompression failure error. 771 struct { 772 ContentType type; /* same as TLSPlaintext.type */ 773 ProtocolVersion version;/* same as TLSPlaintext.version */ 774 uint16 length; 775 opaque fragment[TLSCompressed.length]; 776 } TLSCompressed; 778 length 779 The length (in bytes) of the following TLSCompressed.fragment. 780 The length should not exceed 2^14 + 1024. 782 fragment 783 The compressed form of TLSPlaintext.fragment. 785 Note: A CompressionMethod.null operation is an identity operation; no 786 fields are altered. 788 Implementation note: 789 Decompression functions are responsible for ensuring that 790 messages cannot cause internal buffer overflows. 792 5.3.3. Record payload protection 794 The encryption and MAC functions translate a TLSCompressed structure 795 into a TLSCiphertext. The decryption functions reverse the process. 796 Transmissions also include a sequence number so that missing, 797 altered, or extra messages are detectable. 799 struct { 800 ContentType type; 801 ProtocolVersion version; 802 uint16 length; 803 select (CipherSpec.cipher_type) { 804 case stream: GenericStreamCipher; 805 case block: GenericBlockCipher; 806 } fragment; 807 } TLSCiphertext; 809 type 810 The type field is identical to TLSCompressed.type. 812 version 813 The version field is identical to TLSCompressed.version. 815 length 816 The length (in bytes) of the following TLSCiphertext.fragment. 817 The length may not exceed 2^14 + 2048. 819 fragment 820 The encrypted form of TLSCompressed.fragment, with the MAC. 822 5.3.3.1. Null or standard stream cipher 824 Stream ciphers (including BulkCipherAlgorithm.null - see Appendix 825 A.7) convert TLSCompressed.fragment structures to and from stream 826 TLSCiphertext.fragment structures. 828 stream-ciphered struct { 829 opaque content[TLSCompressed.length]; 830 opaque MAC[CipherSpec.hash_size]; 831 } GenericStreamCipher; 833 The MAC is generated as: 835 | HMAC_hash(MAC_write_secret, seq_num + TLSCompressed.version + 836 | TLSCompressed.type + TLSCompressed.length + 837 | TLSCompressed.fragment)); 839 where "+" denotes concatenation. 841 seq_num 842 The sequence number for this record. 844 hash 845 The hashing algorithm specified by 846 SecurityParameters.mac_algorithm. 848 Note that the MAC is computed before encryption. The stream cipher 849 encrypts the entire block, including the MAC. For stream ciphers 850 that do not use a synchronization vector (such as RC4), the stream 851 cipher state from the end of one record is simply used on the 852 subsequent packet. If the CipherSuite is TLS_NULL_WITH_NULL_NULL, 853 encryption consists of the identity operation (i.e., the data is not 854 encrypted and the MAC size is zero implying that no MAC is used). 855 TLSCiphertext.length is TLSCompressed.length plus 856 CipherSpec.hash_size. 858 5.3.3.2. CBC block cipher 860 For block ciphers (such as RC2 or DES), the encryption and MAC 861 functions convert TLSCompressed.fragment structures to and from 862 block TLSCiphertext.fragment structures. 864 block-ciphered struct { 865 opaque content[TLSCompressed.length]; 866 opaque MAC[CipherSpec.hash_size]; 867 uint8 padding[GenericBlockCipher.padding_length]; 868 uint8 padding_length; 869 } GenericBlockCipher; 871 The MAC is generated as described in Section 5.3.3.1. 873 padding 874 Padding that is added to force the length of the plaintext to be 875 | an even multiple of the block cipher's block length. The padding 876 | may be any length up to 255 bytes long, as long as it results in 877 | the TLSCiphertext.length being an even multiple of the block 878 | length. Lengths longer than necessary might be desirable to 879 | frustrate attacks on a protocol based on analysis of the lengths 880 | of exchanged messages. The padding data must be filled with the 881 | padding length repeated to fill the array. 883 padding_length 884 The length of the padding must be less than the cipher's block 885 length and may be zero. The padding length should be such that 886 the total size of the GenericBlockCipher structure is a multiple 887 of the cipher's block length. 889 The encrypted data length (TLSCiphertext.length) is one more than 890 the sum of TLSCompressed.length, CipherSpec.hash_size, and 891 padding_length. 893 Example: If the block length is 8 bytes, the content length 894 | (TLSCompressed.length) is 61 bytes, and the MAC length is 20 895 | bytes, the length before padding is 82 bytes. Thus, the 896 | padding length modulo 8 must be equal to 6 in order to make 897 | the total length an even multiple of 8 bytes (the block 898 | length). The padding length can be 6, 14, 22, and so on, 899 | through 254. If the padding length were the minimum necessary, 900 | 6, the padding would be 6 bytes, each containing the value 6. 902 |Note: With block ciphers in CBC mode (Cipher Block Chaining) the 903 initialization vector (IV) for the first record is generated 904 with the other keys and secrets when the security parameters are 905 set. The IV for subsequent records is the last ciphertext block 906 from the previous record. 908 5.4. Key calculation 910 The Record Protocol requires an algorithm to generate keys, IVs, and 911 MAC secrets from the security parameters provided by the handshake 912 protocol. 914 The master secret is hashed into a sequence of secure bytes, which 915 are assigned to the MAC secrets, keys, and non-export IVs required 916 by the current connection state (see Appendix A.7). CipherSpecs 917 require a client write MAC secret, a server write MAC secret, a 918 client write key, a server write key, a client write IV, and a 919 server write IV, which are generated from the master secret in that 920 order. Unused values are empty. 922 When generating keys and MAC secrets, the master secret is used as 923 an entropy source, and the random values provide unencrypted salt 924 material and IVs for exportable ciphers. 926 To generate the key material, compute 928 | key_block = PRF(SecurityParameters.master_secret, 929 | SecurityParameters.master_secret + 930 | SecurityParameters.server_random + 931 | SecurityParameters.client_random); 933 until enough output has been generated. Then the key_block is 934 partitioned as follows: 936 client_write_MAC_secret[SecurityParameters.hash_size] 937 server_write_MAC_secret[SecurityParameters.hash_size] 938 client_write_key[SecurityParameters.key_material] 939 server_write_key[SecurityParameters.key_material] 940 client_write_IV[SecurityParameters.IV_size] 941 server_write_IV[SecurityParameters.IV_size] 943 The client_write_IV and server_write_IV are only generated for 944 non-export block ciphers. For exportable block ciphers, the 945 initialization vectors are generated later, as described below. Any 946 extra key_block material is discarded. 948 Implementation note: 949 The cipher spec which is defined in this document which requires 950 the most material is 3DES_EDE_CBC_SHA: it requires 2 x 24 byte 951 keys, 2 x 20 byte MAC secrets, and 2 x 8 byte IVs, for a total 952 of 104 bytes of key material. This will require iterating the 953 | PRF algorithm seven times, through 'GGGGGGG'. 955 Exportable encryption algorithms (for which CipherSpec.is_exportable 956 is true) require additional processing as follows to derive their 957 final write keys: 959 | final_client_write_key = 960 | PRF(SecurityParameters.client_write_key, 961 | SecurityParameters.client_random + 962 | SecurityParameters.server_random); 963 | final_server_write_key = 964 | PRF(SecurityParameters.server_write_key, 965 | SecurityParameters.client_random + 966 | SecurityParameters.server_random); 968 | Exportable encryption algorithms derive their IVs solely from the 969 | random messages: 971 | iv_block = PRF("", SecurityParameters.client_random + 972 | SecurityParameters.server_random); 973 | The iv_block is partitioned into two initialization vectors as the 974 | key_block was above: 976 | client_write_IV[SecurityParameters.IV_size] 977 | server_write_IV[SecurityParameters.IV_size] 979 | Note that the PRF is used without a secret in this case: this just 980 | means that the secret has a length of zero bytes and contributes 981 | nothing to the hashing in the PRF. 983 5.4.1. Export key generation example 985 TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 requires five random bytes for 986 each of the two encryption keys and 16 bytes for each of the MAC 987 keys, for a total of 42 bytes of key material. MD5 produces 16 bytes 988 | of output per call, so the PRF will iterate three times internally. 989 | The PRF output is stored in the key_block. The key_block is 990 | partitioned, and the write keys are salted because this is an 991 | exportable encryption algorithm. 993 | key_block = PRF(master_secret, 994 | master_secret + 995 | server_random + 996 | client_random)[0..41] 997 client_write_MAC_secret = key_block[0..15] 998 server_write_MAC_secret = key_block[16..31] 999 client_write_key = key_block[32..36] 1000 server_write_key = key_block[37..41] 1001 | final_client_write_key = PRF(client_write_key, 1002 | client_random + 1003 | server_random)[0..15] 1004 | final_server_write_key = PRF(server_write_key, 1005 | client_random + 1006 | server_random)[0..15] 1007 | iv_block = PRF("", client_random + 1008 | server_random)[0..15] 1009 | client_write_IV = iv_block[0..7] 1010 | server_write_IV = iv_block[8..15] 1012 6. The TLS Handshake Protocol 1014 The TLS Handshake Protocol consists of a suite of three 1015 sub-protocols which are used to allow peers to agree upon security 1016 parameters for the record layer, authenticate themselves, 1017 instantiate negotiated security parameters, and report error 1018 conditions to each other. 1020 The Handshake Protocol is responsible for negotiating a session, 1021 which consists of the following items: 1023 session identifier 1024 An arbitrary byte sequence chosen by the server to identify an 1025 active or resumable session state. 1027 peer certificate 1028 X509v3[X509] certificate of the peer. This element of the state 1029 may be null. 1031 compression method 1032 The algorithm used to compress data prior to encryption. 1034 cipher spec 1035 Specifies the bulk data encryption algorithm (such as null, DES, 1036 etc.) and a MAC algorithm (such as MD5 or SHA). It also defines 1037 cryptographic attributes such as the hash_size. (See Appendix 1038 A.7 for formal definition) 1040 master secret 1041 48-byte secret shared between the client and server. 1043 is resumable 1044 A flag indicating whether the session can be used to initiate 1045 new connections. 1047 These items are then used to create security parameters for use by 1048 the Record Layer when protecting application data. Many connections 1049 can be instantiated using the same session through the resumption 1050 feature of the TLS Handshake Protocol. 1052 6.1. Change cipher spec protocol 1054 The change cipher spec protocol exists to signal transitions in 1055 ciphering strategies. The protocol consists of a single message, 1056 which is encrypted and compressed under the current (not the 1057 pending) connection state. The message consists of a single byte of 1058 value 1. 1060 struct { 1061 enum { change_cipher_spec(1), (255) } type; 1062 } ChangeCipherSpec; 1064 The change cipher spec message is sent by both the client and server 1065 to notify the receiving party that subsequent records will be 1066 protected under the newly negotiated CipherSpec and keys. Reception 1067 of this message causes the receiver to instruct the Record Layer to 1068 immediately copy the read pending state into the read current state. 1069 Immediately after sending this message, the sender should instruct 1070 the record layer to make the write pending state the write active 1071 state. (See section 5.1.) The change cipher spec message is sent 1072 during the handshake after the security parameters have been agreed 1073 upon, but before the verifying finished message is sent (see section 1074 6.4.9). 1076 6.2. Alert protocol 1078 One of the content types supported by the TLS Record layer is the 1079 alert type. Alert messages convey the severity of the message and a 1080 description of the alert. Alert messages with a level of fatal 1081 result in the immediate termination of the connection. In this case, 1082 other connections corresponding to the session may continue, but the 1083 session identifier must be invalidated, preventing the failed 1084 session from being used to establish new connections. Like other 1085 messages, alert messages are encrypted and compressed, as specified 1086 by the current connection state. 1088 enum { warning(1), fatal(2), (255) } AlertLevel; 1090 enum { 1091 close_notify(0), 1092 unexpected_message(10), 1093 bad_record_mac(20), 1094 | decryption_failed(21), 1095 | record_overflow(22), 1096 decompression_failure(30), 1097 handshake_failure(40), 1098 no_certificate(41), 1099 bad_certificate(42), 1100 unsupported_certificate(43), 1101 certificate_revoked(44), 1102 certificate_expired(45), 1103 certificate_unknown(46), 1104 illegal_parameter(47), 1105 | unknown_ca(48), 1106 | access_denied(49), 1107 | decode_error(50), 1108 | decrypt_error(51), 1109 | export_restriction(60), 1110 | protocol_version(70), 1111 | insufficient_security(71), 1112 | internal_error(80), 1113 | user_canceled(90), 1114 | no_renegotiation(100), 1115 (255) 1116 } AlertDescription; 1118 struct { 1119 AlertLevel level; 1120 AlertDescription description; 1121 } Alert; 1123 6.2.1. Closure alerts 1125 The client and the server must share knowledge that the connection 1126 is ending in order to avoid a truncation attack. Either party may 1127 initiate the exchange of closing messages. 1129 close_notify 1130 This message notifies the recipient that the sender will not 1131 send any more messages on this connection. The session becomes 1132 unresumable if any connection is terminated without proper 1133 close_notify messages with level equal to warning. 1135 Either party may initiate a close by sending a close_notify alert. 1136 Any data received after a closure alert is ignored. 1138 Each party is required to send a close_notify alert before closing 1139 the write side of the connection. It is required that the other 1140 party respond with a close_notify alert of its own and close down 1141 the connection immediately, discarding any pending writes. It is not 1142 required for the initiator of the close to wait for the responding 1143 close_notify alert before closing the read side of the connection. 1145 NB: It is assumed that closing a connection reliably delivers 1146 pending data before destroying the transport. 1148 6.2.2. Error alerts 1150 Error handling in the TLS Handshake protocol is very simple. When an 1151 error is detected, the detecting party sends a message to the other 1152 party. Upon transmission or receipt of an fatal alert message, both 1153 parties immediately close the connection. Servers and clients are 1154 required to forget any session-identifiers, keys, and secrets 1155 associated with a failed connection. The following error alerts are 1156 defined: 1158 unexpected_message 1159 An inappropriate message was received. This alert is always 1160 fatal and should never be observed in communication between 1161 proper implementations. 1163 bad_record_mac 1164 This alert is returned if a record is received with an incorrect 1165 MAC. This message is always fatal. 1167 | decryption_failed 1168 | A TLSCiphertext decrypted in an invalid way: either it wasn`t an 1169 | even multiple of the block length or its padding values, when 1170 | checked, weren`t correct. This message is always fatal. 1172 | record_overflow 1173 | A TLSCiphertext record was received which had a length more than 1174 | 2^14+2048 bytes, or a record decrypted to a TLSCompressed record 1175 | with more than 2^14+1024 bytes. This message is always fatal. 1177 decompression_failure 1178 The decompression function received improper input (e.g. data 1179 that would expand to excessive length). This message is always 1180 fatal. 1182 handshake_failure 1183 Reception of a handshake_failure alert message indicates that 1184 the sender was unable to negotiate an acceptable set of security 1185 parameters given the options available. This is a fatal error. 1187 no_certificate 1188 A no_certificate alert message may be sent in response to a 1189 certification request if no appropriate certificate is 1190 available. 1192 bad_certificate 1193 A certificate was corrupt, contained signatures that did not 1194 verify correctly, etc. 1196 unsupported_certificate 1197 A certificate was of an unsupported type. 1199 certificate_revoked 1200 A certificate was revoked by its signer. 1202 certificate_expired 1203 A certificate has expired or is not currently valid. 1205 certificate_unknown 1206 Some other (unspecified) issue arose in processing the 1207 certificate, rendering it unacceptable. 1209 illegal_parameter 1210 A field in the handshake was out of range or inconsistent with 1211 other fields. This is always fatal. 1213 | unknown_ca 1214 | A valid certificate chain or partial chain was received, but the 1215 | certificate was not accepted because the CA certificate could 1216 | not be located or couldn`t be matched with a known, trusted CA. 1217 | This message is always fatal. 1219 | access_denied 1220 | A valid certificate was received, but when access control was 1221 | applied, the sender decided not to proceed with negotiation. 1222 | This message is always fatal. 1224 | decode_error 1225 | A message could not be decoded because some field was out of the 1226 | specified range or the length of the message was incorrect. This 1227 | message is always fatal. 1229 | export_restriction 1230 | A negotiation not in compliance with export restrictions was 1231 | detected; for example, attemption to transfer a 1024 bit 1232 | ephemeral RSA key for the RSA_EXPORT handshake method. This 1233 | message is always fatal. 1235 | protocol_version 1236 | The protocol version the client has attempted to negotiate is 1237 | recognized, but not supported. (For example, old protocol 1238 | versions might be avoided for security reasons). This message is 1239 | always fatal. 1241 | insufficient_security 1242 | Returned instead of handshake_failure when a negotiation has 1243 | failed specifically because the server requires ciphers more 1244 | secure than those supported by the client. This message is 1245 | always fatal. 1247 | internal_error 1248 | An internal error unrelated to the peer or the correctness of 1249 | the protocol makes it impossible to continue (such as a memory 1250 | allocation failure). This message is always fatal. 1252 | user_cancelled 1253 | This handshake is being cancelled for some reason unrelated to a 1254 | protocol failure. If the user cancels an operation after the 1255 | handshake is complete, just closing the connection by sending a 1256 | close_notify is more appropriate. This alert should be followed 1257 | by a close_notify. This message is generally a warning. 1259 | no_renegotiation 1260 | Sent by the client in response to a hello request or by the 1261 | server in response to a client hello after initial handshaking. 1262 | Either of these would normally lead to renegotiation; when that 1263 | is not appropriate, the reciepient should respond with this 1264 | alert; at that point, the original reqester can decide whether 1265 | to proceed with the connection. One case where this would be 1266 | appropriate would be where a server has spawned a process to 1267 | satisfy a request; the process might receive secuirty parameters 1268 | (key length, authentication, etc.) at startup and it might be 1269 | difficult to communicate changes to these parameters after that 1270 | point. This message is always a warning. 1272 For all errors where an alert level is not explicitly specified, the 1273 sending party may determine at its discretion whether this is a 1274 fatal error or not; if an alert with a level of warning is received, 1275 the receiving party may decide at its discretion whether to treat 1276 this as a fatal error or not. However, all messages which are 1277 transmitted with a level of fatal must be treated as fatal messages. 1279 6.3. Handshake Protocol overview 1281 The cryptographic parameters of the session state are produced by 1282 the TLS Handshake Protocol, which operates on top of the TLS Record 1283 Layer. When a TLS client and server first start communicating, they 1284 agree on a protocol version, select cryptographic algorithms, 1285 optionally authenticate each other, and use public-key encryption 1286 techniques to generate shared secrets. 1288 | The TLS Handshake Protocol has the following goals: 1290 - Exchange hello messages to agree on algorithms, exchange random 1291 values, and check for session resumption. 1293 - Exchange the necessary cryptographic parameters to allow the 1294 client and server to agree on a premaster secret. 1296 - Exchange certificates and cryptographic information to allow the 1297 client and server to authenticate themselves. 1299 - Generate a master secret from the premaster secret and exchanged 1300 random values. 1302 - Provide security paramers to the record layer. 1304 - Allow the client and server to verify that their peer has 1305 calculated the same security parameters and that the handshake 1306 occured without tampering by an attacker. 1308 These goals are achieved by the handshake protocol, which can be 1309 summarized as follows: The client sends a client hello message to 1310 which the server must respond with a server hello message, or else a 1311 fatal error will occur and the connection will fail. The client 1312 hello and server hello are used to establish security enhancement 1313 capabilities between client and server. The client hello and server 1314 hello establish the following attributes: Protocol Version, Session 1315 ID, Cipher Suite, and Compression Method. Additionally, two random 1316 values are generated and exchanged: ClientHello.random and 1317 ServerHello.random. 1319 The actual key exchange uses up to four messages: the server 1320 certificate, the server key exchange, the client certificate, and 1321 the client key exchange. New key exchange methods can be created by 1322 specifing a format for these messages and defining the use of the 1323 messages to allow the client and server to agree upon a shared 1324 secret. This secret should be quite long; currently defined key 1325 exchange methods exchange secrets which range from 48 to 128 bytes 1326 in length. 1328 Following the hello messages, the server will send its certificate, 1329 if it is to be authenticated. Additionally, a server key exchange 1330 message may be sent, if it is required (e.g. if their server has no 1331 certificate, or if its certificate is for signing only). If the 1332 server is authenticated, it may request a certificate from the 1333 client, if that is appropriate to the cipher suite selected. Now the 1334 server will send the server hello done message, indicating that the 1335 hello-message phase of the handshake is complete. The server will 1336 then wait for a client response. If the server has sent a 1337 certificate request message, the client must send either the 1338 certificate message or a no_certificate alert. The client key 1339 exchange message is now sent, and the content of that message will 1340 depend on the public key algorithm selected between the client hello 1341 and the server hello. If the client has sent a certificate with 1342 signing ability, a digitally-signed certificate verify message is 1343 sent to explicitly verify the certificate. 1345 At this point, a change cipher spec message is sent by the client, 1346 and the client copies the pending Cipher Spec into the current 1347 Cipher Spec. The client then immediately sends the finished message 1348 under the new algorithms, keys, and secrets. In response, the server 1349 will send its own change cipher spec message, transfer the pending 1350 to the current Cipher Spec, and send its finished message under the 1351 new Cipher Spec. At this point, the handshake is complete and the 1352 client and server may begin to exchange application layer data. (See 1353 flow chart below.) 1355 Client Server 1357 ClientHello --------> 1358 ServerHello 1359 Certificate* 1360 ServerKeyExchange* 1361 CertificateRequest* 1362 <-------- ServerHelloDone 1363 Certificate* 1364 ClientKeyExchange 1365 CertificateVerify* 1366 [ChangeCipherSpec] 1367 Finished --------> 1368 [ChangeCipherSpec] 1369 <-------- Finished 1370 Application Data <-------> Application Data 1372 * Indicates optional or situation-dependent messages that are not 1373 always sent. 1375 Note: To help avoid pipeline stalls, ChangeCipherSpec is an 1376 independent TLS Protocol content type, and is not actually a TLS 1377 handshake message. 1379 When the client and server decide to resume a previous session or 1380 duplicate an existing session (instead of negotiating new security 1381 parameters) the message flow is as follows: 1383 The client sends a ClientHello using the Session ID of the session 1384 to be resumed. The server then checks its session cache for a match. 1385 If a match is found, and the server is willing to re-establish the 1386 connection under the specified session state, it will send a 1387 ServerHello with the same Session ID value. At this point, both 1388 client and server must send change cipher spec messages and proceed 1389 directly to finished messages. Once the re-establishment is 1390 complete, the client and server may begin to exchange application 1391 layer data. (See flow chart below.) If a Session ID match is not 1392 found, the server generates a new session ID and the TLS client and 1393 server perform a full handshake. 1395 Client Server 1397 ClientHello --------> 1398 ServerHello 1399 [ChangeCipherSpec] 1400 <-------- Finished 1401 [ChangeCipherSpec] 1402 Finished --------> 1403 Application Data <-------> Application Data 1405 The contents and significance of each message will be presented in 1406 detail in the following sections. 1408 6.4. Handshake protocol 1410 The TLS Handshake Protocol is one of the defined higher level 1411 clients of the TLS Record Protocol. This protocol is used to 1412 negotiate the secure attributes of a session. Handshake messages are 1413 supplied to the TLS Record Layer, where they are encapsulated within 1414 one or more TLSPlaintext structures, which are processed and 1415 transmitted as specified by the current active session state. 1417 enum { 1418 hello_request(0), client_hello(1), server_hello(2), 1419 certificate(11), server_key_exchange (12), 1420 certificate_request(13), server_hello_done(14), 1421 certificate_verify(15), client_key_exchange(16), 1422 finished(20), (255) 1423 } HandshakeType; 1425 struct { 1426 HandshakeType msg_type; /* handshake type */ 1427 uint24 length; /* bytes in message */ 1428 select (HandshakeType) { 1429 case hello_request: HelloRequest; 1430 case client_hello: ClientHello; 1431 case server_hello: ServerHello; 1432 case certificate: Certificate; 1433 case server_key_exchange: ServerKeyExchange; 1434 case certificate_request: CertificateRequest; 1435 case server_hello_done: ServerHelloDone; 1436 case certificate_verify: CertificateVerify; 1437 case client_key_exchange: ClientKeyExchange; 1438 case finished: Finished; 1439 } body; 1440 } Handshake; 1442 The handshake protocol messages are presented in the order they must 1443 be sent; sending handshake messages in an unexpected order results 1444 | in a fatal error. Unneeded handshake messages can be omitted, 1445 | however. The one exception is the Hello request message, which may 1446 | be sent by the server at any time. 1448 6.4.1. Hello messages 1450 The hello phase messages are used to exchange security enhancement 1451 capabilities between the client and server. When a new session 1452 begins, the Record Layer's connection state encryption, hash, and 1453 compression algorithms are initialized to null. The current 1454 connection state is used for renegotiation messages. 1456 6.4.1.1. Hello request 1458 When this message will be sent: 1459 The hello request message may be sent by the server at any time. 1461 Meaning of this message: 1462 Hello request is a simple notification that the client should 1463 begin the negotiation process anew by sending a client hello 1464 message when convenient. This message will be ignored by the 1465 client if the client is currently negotiating a session. This 1466 message may be ignored by the client if it does not wish to 1467 renegotiate a session. Since handshake messages are intended to 1468 have transmission precedence over application data, it is 1469 expected that the negotiation will begin before no more than a 1470 few records are received from the client. If the server sends a 1471 hello request but does not recieve a client hello in response, 1472 it may close the connection with a fatal alert. 1474 After sending a hello request, servers should not repeat the request 1475 until the subsequent handshake negotiation is complete. 1477 Structure of this message: 1478 struct { } HelloRequest; 1480 Note: This message should never be included in the message hashes 1481 which are maintained throughout the handshake and used in the 1482 finished messages and the certificate verify message. 1484 6.4.1.2. Client hello 1486 When this message will be sent: 1487 When a client first connects to a server it is required to send 1488 the client hello as its first message. The client can also send 1489 a client hello in response to a hello request or on its own 1490 initiative in order to renegotiate the security parameters in an 1491 existing connection. 1493 Structure of this message: 1494 The client hello message includes a random structure, which is 1495 used later in the protocol. 1497 struct { 1498 uint32 gmt_unix_time; 1499 opaque random_bytes[28]; 1500 } Random; 1502 gmt_unix_time 1503 The current time and date in standard UNIX 32-bit format 1504 according to the sender's internal clock. Clocks are not 1505 required to be set correctly by the basic TLS Protocol; higher 1506 level or application protocols may define additional 1507 requirements. 1509 random_bytes 1510 28 bytes generated by a secure random number generator. 1512 The client hello message includes a variable length session 1513 identifier. If not empty, the value identifies a session between the 1514 same client and server whose security parameters the client wishes 1515 to reuse. The session identifier may be from an earlier connection, 1516 this connection, or another currently active connection. The second 1517 option is useful if the client only wishes to update the random 1518 structures and derived values of a connection, while the third 1519 | option makes it possible to establish several independent secure 1520 | connections without repeating the full handshake protocol. These 1521 | independant connections may occur sequentially or simultaneously; a 1522 | SessionID becomes valid when the handshake negotiating it completes 1523 | with the exchange of Finished messages and persists until removed 1524 | due to aging or because a fatal error was encountered on a 1525 | connection associated with the session. The actual contents of the 1526 | SessionID are defined by the server. 1528 opaque SessionID<0..32>; 1530 Warning: 1531 | Because the SessionID is transmitted without encryption or 1532 | immediate MAC protection, servers must not place confidential 1533 | information in session identifiers or let the contents of fake 1534 | session identifiers cause any breach of security. (Note that the 1535 | contents of the handshake as a whole, including the SessionID, 1536 | is protected by the Finished messages exchanged at the end of 1537 | the handshake.) 1539 The CipherSuite list, passed from the client to the server in the 1540 client hello message, contains the combinations of cryptographic 1541 algorithms supported by the client in order of the client's 1542 preference (first choice first). Each CipherSuite defines a key 1543 exchange algorithm, a bulk encryption algorithm (including secret 1544 key length) and a MAC algorithm. The server will select a cipher 1545 suite or, if no acceptable choices are presented, return a handshake 1546 failure alert and close the connection. 1548 uint8 CipherSuite[2]; /* Cryptographic suite selector */ 1550 The client hello includes a list of compression algorithms supported 1551 by the client, ordered according to the client's preference. 1553 enum { null(0), (255) } CompressionMethod; 1555 struct { 1556 ProtocolVersion client_version; 1557 Random random; 1558 SessionID session_id; 1559 CipherSuite cipher_suites<2..2^16-1>; 1560 CompressionMethod compression_methods<1..2^8-1>; 1561 } ClientHello; 1563 client_version 1564 The version of the TLS protocol by which the client wishes to 1565 communicate during this session. This should be the latest 1566 (highest valued) version supported by the client. For this 1567 | version of the specification, the version will be 3.1 (See 1568 Appendix E for details about backward compatibility). 1570 random 1571 A client-generated random structure. 1573 session_id 1574 The ID of a session the client wishes to use for this 1575 connection. This field should be empty if no session_id is 1576 available or the client wishes to generate new security 1577 parameters. 1579 cipher_suites 1580 This is a list of the cryptographic options supported by the 1581 client, with the client's first preference first. If the 1582 session_id field is not empty (implying a session resumption 1583 request) this vector must include at least the cipher_suite from 1584 that session. Values are defined in Appendix A.6. 1586 compression_methods 1587 This is a list of the compression methods supported by the 1588 client, sorted by client preference. If the session_id field is 1589 not empty (implying a session resumption request) it must 1590 include the compression_method from that session. This vector 1591 must contain, and all implementations must support, 1592 CompressionMethod.null. Thus, a client and server will always be 1593 able to agree on a compression method. 1595 After sending the client hello message, the client waits for a 1596 server hello message. Any other handshake message returned by the 1597 server except for a hello request is treated as a fatal error. 1599 Forward compatibility note: 1600 In the interests of forward compatibility, it is permitted for a 1601 client hello message to include extra data after the compression 1602 methods. This data must be included in the handshake hashes, but 1603 must otherwise be ignored. This is the only handshake message 1604 for which this is legal; for all other messages, the amount of 1605 data in the message must match the description of the message 1606 precisely. 1608 6.4.1.3. Server hello 1610 When this message will be sent: 1611 The server will send this message in response to a client hello 1612 message when it was able to find an acceptable set of 1613 algorithms. If it cannot find such a match, it will respond with 1614 a handshake failure alert. 1616 Structure of this message: 1617 struct { 1618 ProtocolVersion server_version; 1619 Random random; 1620 SessionID session_id; 1621 CipherSuite cipher_suite; 1622 CompressionMethod compression_method; 1623 } ServerHello; 1625 server_version 1626 This field will contain the lower of that suggested by the 1627 client in the client hello and the highest supported by the 1628 | server. For this version of the specification, the version is 1629 | 3.1 (See Appendix E for details about backward compatibility). 1631 random 1632 This structure is generated by the server and must be different 1633 from (and independent of) ClientHello.random. 1635 session_id 1636 This is the identity of the session corresponding to this 1637 connection. If the ClientHello.session_id was non-empty, the 1638 server will look in its session cache for a match. If a match is 1639 found and the server is willing to establish the new connection 1640 using the specified session state, the server will respond with 1641 the same value as was supplied by the client. This indicates a 1642 resumed session and dictates that the parties must proceed 1643 directly to the finished messages. Otherwise this field will 1644 contain a different value identifying the new session. The 1645 server may return an empty session_id to indicate that the 1646 session will not be cached and therefore cannot be resumed. 1648 cipher_suite 1649 The single cipher suite selected by the server from the list in 1650 ClientHello.cipher_suites. For resumed sessions this field is 1651 the value from the state of the session being resumed. 1653 compression_method 1654 The single compression algorithm selected by the server from the 1655 list in ClientHello.compression_methods. For resumed sessions 1656 this field is the value from the resumed session state. 1658 6.4.2. Server certificate 1660 When this message will be sent: 1661 The server must send a certificate whenever the agreed-upon key 1662 exchange method is not an anonymous one. This message will 1663 always immediately follow the server hello message. 1665 Meaning of this message: 1666 The certificate type must be appropriate for the selected cipher 1667 suite's key exchange algorithm, and is generally an X.509v3 1668 certificate. It must contain a key which matches the key 1669 exchange method, as follows. Unless otherwise specified, the 1670 signing algorithm for the certificate must be the same as the 1671 algorithm for the certificate key. Unless otherwise specified, 1672 the public key may be of any length. 1674 Key Exchange Algorithm Certificate Key Type 1676 RSA RSA public key; the certificate must 1677 allow the key to be used for encryption. 1679 RSA_EXPORT RSA public key of length greater than 1680 512 bits which can be used for signing, 1681 or a key of 512 bits or shorter which 1682 Can be used for encryption or signing. 1684 DHE_DSS DSS public key. 1686 DHE_DSS_EXPORT DSS public key. 1688 DHE_RSA RSA public key which can be used for 1689 signing. 1691 DHE_RSA_EXPORT RSA public key which can be used for 1692 signing. 1694 DH_DSS Diffie-Hellman key. The algorithm used 1695 to sign the certificate should be DSS. 1697 DH_RSA Diffie-Hellman key. The algorithm used 1698 to sign the certificate should be RSA. 1700 As CipherSuites which specify new key exchange methods are specified 1701 for the TLS Protocol, they will imply certificate format and the 1702 required encoded keying information. 1704 Structure of this message: 1705 opaque ASN.1Cert<1..2^24-1>; 1706 struct { 1707 ASN.1Cert certificate_list<0..2^24-1>; 1708 } Certificate; 1710 certificate_list 1711 | This is a sequence (chain) of X.509v3 certificates. The sender's 1712 | certificate must come first in the list. Each following 1713 | certificate must directly certify the one preceding it. Because 1714 | certificate validation requires that root keys be distributed 1715 | independantly, the self-signed certificate which specifies the 1716 | root certificate authority may optionally be omitted from the 1717 | chain, under the assumption that the remote end must already 1718 | possess it in order to validate it in any case. 1720 The same message type and structure will be used for the client's 1721 | response to a certificate request message. Note that a client may 1722 | send no certificates if it does not have an appropriate certificate 1723 | to send in response to the server's authentication request. 1725 Note: PKCS #7 [PKCS7] is not used as the format for the certificate 1726 vector because PKCS #6 [PKCS6] extended certificates are not 1727 used. Also PKCS #7 defines a SET rather than a SEQUENCE, making 1728 the task of parsing the list more difficult. 1730 6.4.3. Server key exchange message 1732 When this message will be sent: 1733 | This message will be sent immediately after the server 1734 | certificate message (or the server hello message, if this is an 1735 | anonymous negotiation). 1737 The server key exchange message is sent by the server only when 1738 the server certificate message (if sent) does not contain enough 1739 data to allow the client to exchange a premaster secret. This is 1740 true for the following key exchange methods: 1742 RSA_EXPORT (if the public key in the server certificate is 1743 longer than 512 bits) 1744 DHE_DSS 1745 DHE_DSS_EXPORT 1746 DHE_RSA 1747 DHE_RSA_EXPORT 1748 DH_anon 1750 It is not legal to send the server key exchange message for the 1751 following key exchange methods: 1753 RSA 1754 RSA_EXPORT (when the public key in the server certificate is 1755 less than or equal to 512 bits in length) 1756 DH_DSS 1757 DH_RSA 1759 Meaning of this message: 1760 This message conveys cryptographic information to allow the 1761 client to communicate the premaster secret: either an RSA public 1762 key to encrypt the premaster secret with, or a Diffie-Hellman 1763 public key with which the client can complete a key exchange 1764 (with the result being the premaster secret.) 1766 As additional CipherSuites are defined for TLS which include new key 1767 exchange algorithms, the server key exchange message will be sent if 1768 and only if the certificate type associated with the key exchange 1769 algorithm does not provide enough information for the client to 1770 exchange a premaster secret. 1772 Note: According to current US export law, RSA moduli larger than 512 1773 bits may not be used for key exchange in software exported from 1774 the US. With this message, the larger RSA keys encoded in 1775 certificates may be used to sign temporary shorter RSA keys for 1776 the RSA_EXPORT key exchange method. 1778 Structure of this message: 1779 enum { rsa, diffie_hellman } KeyExchangeAlgorithm; 1781 struct { 1782 opaque rsa_modulus<1..2^16-1>; 1783 opaque rsa_exponent<1..2^16-1>; 1784 } ServerRSAParams; 1786 rsa_modulus 1787 The modulus of the server's temporary RSA key. 1789 rsa_exponent 1790 The public exponent of the server's temporary RSA key. 1792 struct { 1793 opaque dh_p<1..2^16-1>; 1794 opaque dh_g<1..2^16-1>; 1795 opaque dh_Ys<1..2^16-1>; 1796 } ServerDHParams; /* Ephemeral DH parameters */ 1798 dh_p 1799 The prime modulus used for the Diffie-Hellman operation. 1801 dh_g 1802 The generator used for the Diffie-Hellman operation. 1804 dh_Ys 1805 The server's Diffie-Hellman public value (g^X mod p). 1807 struct { 1808 select (KeyExchangeAlgorithm) { 1809 case diffie_hellman: 1810 ServerDHParams params; 1811 Signature signed_params; 1812 case rsa: 1813 ServerRSAParams params; 1814 Signature signed_params; 1815 }; 1816 } ServerKeyExchange; 1818 params 1819 The server's key exchange parameters. 1821 signed_params 1822 For non-anonymous key exchanges, a hash of the corresponding 1823 params value, with the signature appropriate to that hash 1824 applied. 1826 md5_hash 1827 MD5(ClientHello.random + ServerHello.random + ServerParams); 1829 sha_hash 1830 SHA(ClientHello.random + ServerHello.random + ServerParams); 1832 enum { anonymous, rsa, dsa } SignatureAlgorithm; 1834 select (SignatureAlgorithm) 1835 { case anonymous: struct { }; 1836 case rsa: 1837 digitally-signed struct { 1838 opaque md5_hash[16]; 1839 opaque sha_hash[20]; 1840 }; 1841 case dsa: 1842 digitally-signed struct { 1843 opaque sha_hash[20]; 1844 }; 1845 } Signature; 1847 6.4.4. Certificate request 1849 When this message will be sent: 1850 A non-anonymous server can optionally request a certificate from 1851 | the client, if appropriate for the selected cipher suite. This 1852 | message, if sent, will immediately follow the Server Key 1853 | Exchange message (if it is sent; otherwise, the Server 1854 | Certificate message). 1856 Structure of this message: 1857 enum { 1858 rsa_sign(1), dss_sign(2), rsa_fixed_dh(3), dss_fixed_dh(4), 1859 rsa_ephemeral_dh(5), dss_ephemeral_dh(6), 1860 (255) 1861 } ClientCertificateType; 1863 opaque DistinguishedName<1..2^16-1>; 1865 struct { 1866 ClientCertificateType certificate_types<1..2^8-1>; 1867 DistinguishedName certificate_authorities<3..2^16-1>; 1868 } CertificateRequest; 1870 certificate_types 1871 This field is a list of the types of certificates requested, 1872 sorted in order of the server's preference. 1874 certificate_authorities 1875 A list of the distinguished names of acceptable certificate 1876 | authorities. These distinguished names may specify a desired 1877 | distinguished name for a root CA or for a subordinate CA; 1878 | thus, this message can be used both to describe known roots 1879 | and a desired authorization space. 1881 Note: DistinguishedName is derived from [X509]. 1883 Note: It is a fatal handshake_failure alert for an anonymous server to 1884 request client identification. 1886 6.4.5. Server hello done 1888 When this message will be sent: 1889 The server hello done message is sent by the server to indicate 1890 the end of the server hello and associated messages. After 1891 sending this message the server will wait for a client response. 1893 Meaning of this message: 1894 This message means that the server is done sending messages to 1895 support the key exchange, and the client can proceed with its 1896 phase of the key exchange. 1898 Upon receipt of the server hello done message the client should 1899 verify that the server provided a valid certificate if required 1900 and check that the server hello parameters are acceptable. 1902 Structure of this message: 1903 struct { } ServerHelloDone; 1905 6.4.6. Client certificate 1907 When this message will be sent: 1908 This is the first message the client can send after receiving a 1909 server hello done message. This message is only sent if the 1910 server requests a certificate. If no suitable certificate is 1911 | available, the client should send a certificate message 1912 | containing no certificates. If client authentication is required 1913 | by the server for the handshake to continue, it may respond with 1914 | a fatal handshake failure alert. Client certificates are sent 1915 | using the Certificate structure defined in Section 6.4.2. 1917 Note: When using a static Diffie-Hellman based key exchange method 1918 (DH_DSS or DH_RSA), if client authentication is requested, the 1919 Diffie-Hellman group and generator encoded in the client's 1920 certificate must match the server specified Diffie-Hellman 1921 parameters if the client's parameters are to be used for the key 1922 exchange. 1924 6.4.7. Client key exchange message 1926 When this message will be sent: 1927 This message is always sent by the client. It will immediately 1928 | follow the client certificate message, if it is sent. Otherwise 1929 | it will be the first message sent by the client after it 1930 | receives the server hello done message. 1932 Meaning of this message: 1933 With this message, the premaster secret is set, either though 1934 direct transmisson of the RSA-encrypted secret, or by the 1935 transmission of Diffie-Hellman parameters which will allow each 1936 side to agree upon the same premaster secret. When the key 1937 exchange method is DH_RSA or DH_DSS, client certification has 1938 been requested, and the client was able to respond with a 1939 certificate which contained a Diffie-Hellman public key whose 1940 parameters (group and generator) matched those specified by the 1941 server in its certificate, this message will not contain any 1942 data. 1944 Structure of this message: 1945 The choice of messages depends on which key exchange method has 1946 been selected. See Section 6.4.3 for the KeyExchangeAlgorithm 1947 definition. 1949 struct { 1950 select (KeyExchangeAlgorithm) { 1951 case rsa: EncryptedPreMasterSecret; 1952 case diffie_hellman: ClientDiffieHellmanPublic; 1953 } exchange_keys; 1954 } ClientKeyExchange; 1956 6.4.7.1. RSA encrypted premaster secret message 1958 Meaning of this message: 1959 If RSA is being used for key agreement and authentication, the 1960 client generates a 48-byte premaster secret, encrypts it using 1961 the public key from the server's certificate or the temporary 1962 RSA key provided in a server key exchange message, and sends the 1963 result in an encrypted premaster secret message. This structure 1964 is a variant of the client key exchange message, not a message 1965 in itself. 1967 Structure of this message: 1968 struct { 1969 ProtocolVersion client_version; 1970 opaque random[46]; 1971 } PreMasterSecret; 1973 client_version 1974 The latest (newest) version supported by the client. This is 1975 | used to detect version roll-back attacks. Upon receiving the 1976 | premaster secret, the server should check that this value 1977 | matches the value transmitted by the client in the client 1978 | hello message. 1980 random 1981 46 securely-generated random bytes. 1983 struct { 1984 public-key-encrypted PreMasterSecret pre_master_secret; 1985 } EncryptedPreMasterSecret; 1987 pre_master_secret 1988 This random value is generated by the client and is used to 1989 generate the master secret, as specified in Section 7.1. 1991 6.4.7.2. Client Diffie-Hellman public value 1993 Meaning of this message: 1994 This structure conveys the client's Diffie-Hellman public value 1995 (Yc) if it was not already included in the client's certificate. 1996 The encoding used for Yc is determined by the enumerated 1997 PublicValueEncoding. This structure is a variant of the client 1998 key exchange message, not a message in itself. 2000 Structure of this message: 2001 enum { implicit, explicit } PublicValueEncoding; 2003 implicit 2004 If the client certificate already contains a suitable 2005 Diffie-Hellman key, then Yc is implicit and does not need to 2006 | be sent again. In this case, the Client Key Exchange message 2007 | will be sent, but will be empty. 2009 explicit 2010 Yc needs to be sent. 2012 struct { 2013 select (PublicValueEncoding) { 2014 case implicit: struct { }; 2015 case explicit: opaque dh_Yc<1..2^16-1>; 2016 } dh_public; 2017 } ClientDiffieHellmanPublic; 2019 dh_Yc 2020 The client's Diffie-Hellman public value (Yc). 2022 6.4.8. Certificate verify 2024 When this message will be sent: 2025 This message is used to provide explicit verification of a 2026 client certificate. This message is only sent following a client 2027 certificate that has signing capability (i.e. all certificates 2028 except those containing fixed Diffie-Hellman parameters). When 2029 sent, it will immediately follow the client key exchange 2030 message. 2032 Structure of this message: 2033 struct { 2034 Signature signature; 2035 } CertificateVerify; 2037 The Signature type is defined in 6.4.3. 2039 CertificateVerify.signature.md5_hash 2040 | HMAC_MD5(master_secret, handshake_messages); 2042 Certificate.signature.sha_hash 2043 | HMAC_SHA(master_secret, handshake_messages); 2045 Here handshake_messages refers to all handshake messages sent or 2046 received starting at client hello up to but not including this 2047 message, including the type and length fields of the handshake 2048 messages. This is the concatenation of all the Handshake structures 2049 as defined in 6.4 exchanged thus far. 2051 6.4.9. Finished 2053 When this message will be sent: 2054 A finished message is always sent immediately after a change 2055 cipher spec message to verify that the key exchange and 2056 authentication processes were successful. It is essential that a 2057 change cipher spec message be received between the other 2058 handshake messages and the Finished message. 2060 Meaning of this message: 2061 The finished message is the first protected with the 2062 just-negotiated algorithms, keys, and secrets. No acknowledgment 2063 of the finished message is required; parties may begin sending 2064 encrypted data immediately after sending the finished message. 2065 Recipients of finished messages must verify that the contents 2066 are correct. 2068 enum { client(0x434C4E54), server(0x53525652) } Sender; 2070 struct { 2071 opaque md5_hash[16]; 2072 opaque sha_hash[20]; 2073 } Finished; 2075 md5_hash 2076 | HMAC_MD5(master_secret, handshake_messages + Sender); 2078 sha_hash 2079 | HMAC_SHA(master_secret, handshake_messages + Sender); 2081 handshake_messages 2082 All of the data from all handshake messages up to but not 2083 including this message. This is only data visible at the 2084 handshake layer and does not include record layer headers. 2085 This is the concatenation of all the Handshake structures as 2086 defined in 6.4 exchanged thus far. 2088 It is a fatal error if a finished message is not preceeded by a 2089 change cipher spec message at the appropriate point in the 2090 handshake. 2092 The hash contained in finished messages sent by the server 2093 incorporate Sender.server; those sent by the client incorporate 2094 Sender.client. The value handshake_messages includes all handshake 2095 messages starting at client hello up to, but not including, this 2096 finished message. This may be different from handshake_messages in 2097 Section 6.4.8 because it would include the certificate verify 2098 message (if sent). Also, the handshake_messages for the finished 2099 message sent by the client will be different from that for the 2100 finished message sent by the server, because the one which is sent 2101 second will include the prior one. 2103 Note: Change cipher spec messages are not handshake messages and are 2104 | not included in the hash computations. Also, Hello Request 2105 | messages are omitted from handshake hashes. 2107 7. Cryptographic computations 2109 In order to begin connection protection, the TLS Record Protocol 2110 requires specification of a suite of algorithms, a master secret, 2111 and the client and server random values. The authentication, 2112 encryption, and MAC algorithms are determined by the cipher_suite 2113 selected by the server and revealed in the server hello message. The 2114 compression algorithm is negotiated in the hello messages, and the 2115 random values are exchanged in the hello messages. All that remains 2116 is to calculate the master secret. 2118 7.1. Computing the master secret 2120 For all key exchange methods, the same algorithm is used to convert 2121 the pre_master_secret into the master_secret. The pre_master_secret 2122 should be deleted from memory once the master_secret has been 2123 computed. 2125 | master_secret = PRF(pre_master_secret, pre_master_secret + 2126 | ClientHello.random + ServerHello.random); 2128 The master secret is always exactly 48 bytes in length. The length 2129 of the premaster secret will vary depending on key exchange method. 2131 7.1.1. RSA 2133 When RSA is used for server authentication and key exchange, a 2134 48-byte pre_master_secret is generated by the client, encrypted 2135 under the server's public key, and sent to the server. The server 2136 uses its private key to decrypt the pre_master_secret. Both parties 2137 then convert the pre_master_secret into the master_secret, as 2138 specified above. 2140 RSA digital signatures are performed using PKCS #1 [PKCS1] block 2141 type 1. RSA public key encryption is performed using PKCS #1 block 2142 type 2. 2144 7.1.2. Diffie-Hellman 2146 A conventional Diffie-Hellman computation is performed. The 2147 negotiated key (Z) is used as the pre_master_secret, and is 2148 converted into the master_secret, as specified above. 2150 Note: Diffie-Hellman parameters are specified by the server, and may 2151 be either ephemeral or contained within the server's 2152 certificate. 2154 8. Application data protocol 2156 Application data messages are carried by the Record Layer and are 2157 fragmented, compressed and encrypted based on the current connection 2158 state. The messages are treated as transparent data to the record 2159 layer. 2161 A. Protocol constant values 2163 This section describes protocol types and constants. 2165 A.1. Reserved port assignments 2167 At the present time TLS is implemented using TCP/IP as the base 2168 | networking technology, although the protocol should be useful over 2169 | any transport which can provide a reliable stream connection. The 2170 IANA reserved the following Internet Protocol [IP] port numbers for 2171 use in conjunction with the SSL 3.0 Protocol, which we presume will 2172 be used by TLS as well. 2174 443 Reserved for use by Hypertext Transfer Protocol with SSL (https) 2176 465 Reserved for use by Simple Mail Transfer Protocol with SSL 2177 (ssmtp). 2179 563 Reserved for use by Network News Transfer Protocol with SSL 2180 (snntp). 2182 636 Reserved for Light Directory Access Protocol with SSL (ssl-ldap) 2184 990 Reserved (pending) for File Transfer Protocol with SSL (ftps) 2186 995 Reserved for Post Office Protocol with SSL (spop3) 2188 A.2. Record layer 2190 struct { 2191 uint8 major, minor; 2192 } ProtocolVersion; 2194 | ProtocolVersion version = { 3, 1 }; /* TLS v1.0 */ 2196 enum { 2197 change_cipher_spec(20), alert(21), handshake(22), 2198 application_data(23), (255) 2199 } ContentType; 2201 struct { 2202 ContentType type; 2203 ProtocolVersion version; 2204 uint16 length; 2205 opaque fragment[TLSPlaintext.length]; 2206 } TLSPlaintext; 2208 struct { 2209 ContentType type; 2210 ProtocolVersion version; 2211 uint16 length; 2212 opaque fragment[TLSCompressed.length]; 2213 } TLSCompressed; 2215 struct { 2216 ContentType type; 2217 ProtocolVersion version; 2218 uint16 length; 2219 select (CipherSpec.cipher_type) { 2220 case stream: GenericStreamCipher; 2221 case block: GenericBlockCipher; 2222 } fragment; 2223 } TLSCiphertext; 2225 stream-ciphered struct { 2226 opaque content[TLSCompressed.length]; 2227 opaque MAC[CipherSpec.hash_size]; 2228 } GenericStreamCipher; 2230 block-ciphered struct { 2231 opaque content[TLSCompressed.length]; 2232 opaque MAC[CipherSpec.hash_size]; 2233 uint8 padding[GenericBlockCipher.padding_length]; 2234 uint8 padding_length; 2235 } GenericBlockCipher; 2237 A.3. Change cipher specs message 2239 struct { 2240 enum { change_cipher_spec(1), (255) } type; 2241 } ChangeCipherSpec; 2243 A.4. Alert messages 2245 enum { warning(1), fatal(2), (255) } AlertLevel; 2247 enum { 2248 close_notify(0), 2249 unexpected_message(10), 2250 bad_record_mac(20), 2251 decompression_failure(30), 2252 handshake_failure(40), 2253 no_certificate(41), 2254 bad_certificate(42), 2255 unsupported_certificate(43), 2256 certificate_revoked(44), 2257 certificate_expired(45), 2258 certificate_unknown(46), 2259 illegal_parameter (47), 2260 (255) 2261 } AlertDescription; 2263 struct { 2264 AlertLevel level; 2265 AlertDescription description; 2266 } Alert; 2268 A.5. Handshake protocol 2270 enum { 2271 hello_request(0), client_hello(1), server_hello(2), 2272 certificate(11), server_key_exchange (12), 2273 certificate_request(13), server_done(14), 2274 certificate_verify(15), client_key_exchange(16), 2275 finished(20), (255) 2276 } HandshakeType; 2278 struct { 2279 HandshakeType msg_type; 2280 uint24 length; 2281 select (HandshakeType) { 2282 case hello_request: HelloRequest; 2283 case client_hello: ClientHello; 2284 case server_hello: ServerHello; 2285 case certificate: Certificate; 2286 case server_key_exchange: ServerKeyExchange; 2287 case certificate_request: CertificateRequest; 2288 case server_done: ServerHelloDone; 2289 case certificate_verify: CertificateVerify; 2290 case client_key_exchange: ClientKeyExchange; 2291 case finished: Finished; 2292 } body; 2293 } Handshake; 2295 A.5.1. Hello messages 2297 struct { } HelloRequest; 2299 struct { 2300 uint32 gmt_unix_time; 2301 opaque random_bytes[28]; 2302 } Random; 2304 opaque SessionID<0..32>; 2306 uint8 CipherSuite[2]; 2308 enum { null(0), (255) } CompressionMethod; 2310 struct { 2311 ProtocolVersion client_version; 2312 Random random; 2313 SessionID session_id; 2314 CipherSuite cipher_suites<0..2^16-1>; 2315 CompressionMethod compression_methods<0..2^8-1>; 2316 } ClientHello; 2318 struct { 2319 ProtocolVersion server_version; 2320 Random random; 2321 SessionID session_id; 2322 CipherSuite cipher_suite; 2323 CompressionMethod compression_method; 2324 } ServerHello; 2326 A.5.2. Server authentication and key exchange messages 2328 opaque ASN.1Cert<2^24-1>; 2330 struct { 2331 ASN.1Cert certificate_list<1..2^24-1>; 2332 } Certificate; 2334 enum { rsa, diffie_hellman } KeyExchangeAlgorithm; 2336 struct { 2337 opaque RSA_modulus<1..2^16-1>; 2338 opaque RSA_exponent<1..2^16-1>; 2339 } ServerRSAParams; 2341 struct { 2342 opaque DH_p<1..2^16-1>; 2343 opaque DH_g<1..2^16-1>; 2344 opaque DH_Ys<1..2^16-1>; 2345 } ServerDHParams; 2347 struct { 2348 select (KeyExchangeAlgorithm) { 2349 case diffie_hellman: 2350 ServerDHParams params; 2351 Signature signed_params; 2352 case rsa: 2353 ServerRSAParams params; 2354 Signature signed_params; 2355 }; 2356 } ServerKeyExchange; 2358 enum { anonymous, rsa, dsa } SignatureAlgorithm; 2360 select (SignatureAlgorithm) 2361 { case anonymous: struct { }; 2362 case rsa: 2363 digitally-signed struct { 2364 opaque md5_hash[16]; 2365 opaque sha_hash[20]; 2366 }; 2367 case dsa: 2368 digitally-signed struct { 2369 opaque sha_hash[20]; 2370 }; 2371 } Signature; 2372 enum { 2373 RSA_sign(1), DSS_sign(2), RSA_fixed_DH(3), 2374 DSS_fixed_DH(4), RSA_ephemeral_DH(5), DSS_ephemeral_DH(6), 2375 (255) 2376 } CertificateType; 2378 opaque DistinguishedName<1..2^16-1>; 2380 struct { 2381 CertificateType certificate_types<1..2^8-1>; 2382 DistinguishedName certificate_authorities<3..2^16-1>; 2383 } CertificateRequest; 2385 struct { } ServerHelloDone; 2387 A.5.3. Client authentication and key exchange messages 2389 struct { 2390 select (KeyExchangeAlgorithm) { 2391 case rsa: EncryptedPreMasterSecret; 2392 case diffie_hellman: DiffieHellmanClientPublicValue; 2393 } exchange_keys; 2394 } ClientKeyExchange; 2396 struct { 2397 ProtocolVersion client_version; 2398 opaque random[46]; 2399 } PreMasterSecret; 2401 struct { 2402 public-key-encrypted PreMasterSecret pre_master_secret; 2403 } EncryptedPreMasterSecret; 2405 enum { implicit, explicit } PublicValueEncoding; 2407 struct { 2408 select (PublicValueEncoding) { 2409 case implicit: struct {}; 2410 case explicit: opaque DH_Yc<1..2^16-1>; 2411 } dh_public; 2412 } ClientDiffieHellmanPublic; 2414 struct { 2415 Signature signature; 2416 } CertificateVerify; 2418 A.5.4. Handshake finalization message 2420 struct { 2421 opaque md5_hash[16]; 2422 opaque sha_hash[20]; 2423 } Finished; 2425 A.6. The CipherSuite 2427 The following values define the CipherSuite codes used in the client 2428 hello and server hello messages. 2430 A CipherSuite defines a cipher specification supported in TLS 2431 Version 1.0. 2433 CipherSuite TLS_NULL_WITH_NULL_NULL = { 0x00,0x00 }; 2435 The following CipherSuite definitions require that the server 2436 provide an RSA certificate that can be used for key exchange. The 2437 server may request either an RSA or a DSS signature-capable 2438 certificate in the certificate request message. 2440 CipherSuite TLS_RSA_WITH_NULL_MD5 = { 0x00,0x01 }; 2441 CipherSuite TLS_RSA_WITH_NULL_SHA = { 0x00,0x02 }; 2442 CipherSuite TLS_RSA_EXPORT_WITH_RC4_40_MD5 = { 0x00,0x03 }; 2443 CipherSuite TLS_RSA_WITH_RC4_128_MD5 = { 0x00,0x04 }; 2444 CipherSuite TLS_RSA_WITH_RC4_128_SHA = { 0x00,0x05 }; 2445 CipherSuite TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 = { 0x00,0x06 }; 2446 CipherSuite TLS_RSA_WITH_IDEA_CBC_SHA = { 0x00,0x07 }; 2447 CipherSuite TLS_RSA_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x08 }; 2448 CipherSuite TLS_RSA_WITH_DES_CBC_SHA = { 0x00,0x09 }; 2449 CipherSuite TLS_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x0A }; 2451 The following CipherSuite definitions are used for 2452 server-authenticated (and optionally client-authenticated) 2453 Diffie-Hellman. DH denotes cipher suites in which the server's 2454 certificate contains the Diffie-Hellman parameters signed by the 2455 certificate authority (CA). DHE denotes ephemeral Diffie-Hellman, 2456 where the Diffie-Hellman parameters are signed by a DSS or RSA 2457 certificate, which has been signed by the CA. The signing algorithm 2458 | used is specified after the DH or DHE parameter. The server can 2459 | request an RSA or DSS signature-capable certificate from the client 2460 | for client authentication or it may request a Diffie-Hellman 2461 | certificate. Any Diffie-Hellman certificate provided by the client 2462 | must use the parameters (group and generator) described by the 2463 | server. 2465 CipherSuite TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x0B }; 2466 CipherSuite TLS_DH_DSS_WITH_DES_CBC_SHA = { 0x00,0x0C }; 2467 CipherSuite TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA = { 0x00,0x0D }; 2468 CipherSuite TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x0E }; 2469 CipherSuite TLS_DH_RSA_WITH_DES_CBC_SHA = { 0x00,0x0F }; 2470 CipherSuite TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x10 }; 2471 CipherSuite TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x11 }; 2472 CipherSuite TLS_DHE_DSS_WITH_DES_CBC_SHA = { 0x00,0x12 }; 2473 CipherSuite TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA = { 0x00,0x13 }; 2474 CipherSuite TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x14 }; 2475 CipherSuite TLS_DHE_RSA_WITH_DES_CBC_SHA = { 0x00,0x15 }; 2476 CipherSuite TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x16 }; 2478 The following cipher suites are used for completely anonymous 2479 Diffie-Hellman communications in which neither party is 2480 authenticated. Note that this mode is vulnerable to 2481 | man-in-the-middle attacks and is therefore deprecated. 2483 CipherSuite TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 = { 0x00,0x17 }; 2484 CipherSuite TLS_DH_anon_WITH_RC4_128_MD5 = { 0x00,0x18 }; 2485 CipherSuite TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x19 }; 2486 CipherSuite TLS_DH_anon_WITH_DES_CBC_SHA = { 0x00,0x1A }; 2487 CipherSuite TLS_DH_anon_WITH_3DES_EDE_CBC_SHA = { 0x00,0x1B }; 2489 Note: All cipher suites whose first byte is 0xFF are considered 2490 private and can be used for defining local/experimental 2491 algorithms. Interoperability of such types is a local matter. 2493 Note: Additional cipher suites will be considered for implementation 2494 only with submission of notarized letters from two independent 2495 entities. Netscape Communications Corp. will act as an interim 2496 registration office, until a public standards body assumes 2497 control of TLS. 2499 A.7. The Security Parameters 2501 These security parameters are determined by the TLS Handshake 2502 Protocol and provided as parameters to the TLS Record Layer in order 2503 to initialize a connection state. SecurityParameters includes: 2505 enum { null(0), (255) } CompressionMethod; 2507 enum { server, client } ConnectionEnd; 2509 enum { null, rc4, rc2, des, 3des, des40 } BulkCipherAlgorithm; 2511 enum { stream, block } CipherType; 2513 enum { true, false } IsExportable; 2515 enum { null, md5, sha } MACAlgorithm; 2517 /* The algorithms specified in CompressionMethod, 2518 BulkCipherAlgorithm, and MACAlgorithm may be added to. */ 2520 struct { 2521 ConnectionEnd entity; 2522 BulkCipherAlgorithm bulk_cipher_algorithm; 2523 CipherType cipher_type; 2524 uint8 key_size; 2525 uint8 key_material_length; 2526 IsExportable is_exportable; 2527 MACAlgorithm mac_algorithm; 2528 uint8 hash_size; 2529 uint8 whitener_length; 2530 CompressionMethod compression_algorithm; 2531 opaque master_secret[48]; 2532 opaque client_random[32]; 2533 opaque server_random[32]; 2534 } SecurityParameters; 2536 B. Glossary 2538 application protocol 2539 An application protocol is a protocol that normally layers 2540 directly on top of the transport layer (e.g., TCP/IP). Examples 2541 include HTTP, TELNET, FTP, and SMTP. 2543 asymmetric cipher 2544 See public key cryptography. 2546 authentication 2547 Authentication is the ability of one entity to determine the 2548 identity of another entity. 2550 block cipher 2551 A block cipher is an algorithm that operates on plaintext in 2552 groups of bits, called blocks. 64 bits is a typical block size. 2554 bulk cipher 2555 A symmetric encryption algorithm used to encrypt large 2556 quantities of data. 2558 | cipher block chaining (CBC) 2559 | CBC is a mode in which every plaintext block encrypted with a 2560 | block cipher is first exclusive-ORed with the previous 2561 | ciphertext block (or, in the case of the first block, with the 2562 | initialization vector). For decryption, every block is first 2563 | decrypted, then exclusive-ORed with the previous ciphertext 2564 | block (or IV). 2566 certificate 2567 As part of the X.509 protocol (a.k.a. ISO Authentication 2568 framework), certificates are assigned by a trusted Certificate 2569 Authority and provide verification of a party's identity and may 2570 also supply its public key. 2572 client 2573 The application entity that initiates a connection to a server 2575 client write key 2576 The key used to encrypt data written by the client. 2578 client write MAC secret 2579 The secret data used to authenticate data written by the client. 2581 connection 2582 A connection is a transport (in the OSI layering model 2583 definition) that provides a suitable type of service. For TLS, 2584 such connections are peer to peer relationships. The connections 2585 are transient. Every connection is associated with one session. 2587 Data Encryption Standard 2588 DES is a very widely used symmetric encryption algorithm. DES is 2589 | a block cipher with a 56 bit key and an 8 byte block size. Note 2590 | that in TLS, for key generation purposes, DES is treated as 2591 | having an 8 byte key length (64 bits), but it still only 2592 | provides 56 bits of protection. DES can also be operated in a 2593 | mode where three independant keys and three encryptions are used 2594 | for each block of data; this uses 168 bits of key (24 bytes in 2595 | the TLS key generation method) and provides the equivalent of 2596 | 112 bits of security. [DES], [3DES] 2598 Digital Signature Standard (DSS) 2599 A standard for digital signing, including the Digital Signing 2600 Algorithm, approved by the National Institute of Standards and 2601 Technology, defined in NIST FIPS PUB 186, "Digital Signature 2602 Standard," published May, 1994 by the U.S. Dept. of Commerce. 2603 [DSS] 2605 digital signatures 2606 Digital signatures utilize public key cryptography and one-way 2607 hash functions to produce a signature of the data that can be 2608 authenticated, and is difficult to forge or repudiate. 2610 handshake 2611 An initial negotiation between client and server that 2612 establishes the parameters of their transactions. 2614 Initialization Vector (IV) 2615 When a block cipher is used in CBC mode, the initialization 2616 vector is exclusive-ORed with the first plaintext block prior to 2617 encryption. 2619 IDEA 2620 A 64-bit block cipher designed by Xuejia Lai and James Massey. 2621 [IDEA] 2623 Message Authentication Code (MAC) 2624 A Message Authentication Code is a one-way hash computed from a 2625 | message and some secret data. It is difficult to forge without 2626 | knowing the secret data and it is difficult to find messages 2627 | which hash to the same MAC. Its purpose is to detect if the 2628 | message has been altered. 2630 master secret 2631 Secure secret data used for generating encryption keys, MAC 2632 secrets, and IVs. 2634 MD5 2635 MD5 is a secure hashing function that converts an arbitrarily 2636 | long data stream into a digest of fixed size (16 bytes). [MD5] 2638 public key cryptography 2639 A class of cryptographic techniques employing two-key ciphers. 2640 Messages encrypted with the public key can only be decrypted 2641 with the associated private key. Conversely, messages signed 2642 with the private key can be verified with the public key. 2644 one-way hash function 2645 A one-way transformation that converts an arbitrary amount of 2646 data into a fixed-length hash. It is computationally hard to 2647 reverse the transformation or to find collisions. MD5 and SHA 2648 are examples of one-way hash functions. 2650 RC2, RC4 2651 Proprietary bulk ciphers from RSA Data Security, Inc. (There is 2652 no good reference to these as they are unpublished works; 2653 however, see [RSADSI]). RC2 is block cipher and RC4 is a stream 2654 cipher. 2656 RSA 2657 A very widely used public-key algorithm that can be used for 2658 either encryption or digital signing. [RSA] 2660 salt 2661 Non-secret random data used to make export encryption keys 2662 resist precomputation attacks. 2664 server 2665 The server is the application entity that responds to requests 2666 for connections from clients. The server is passive, waiting for 2667 requests from clients. 2669 session 2670 A TLS session is an association between a client and a server. 2671 Sessions are created by the handshake protocol. Sessions define 2672 a set of cryptographic security parameters, which can be shared 2673 among multiple connections. Sessions are used to avoid the 2674 expensive negotiation of new security parameters for each 2675 connection. 2677 session identifier 2678 A session identifier is a value generated by a server that 2679 identifies a particular session. 2681 server write key 2682 The key used to encrypt data written by the server. 2684 server write MAC secret 2685 The secret data used to authenticate data written by the server. 2687 SHA 2688 The Secure Hash Algorithm is defined in FIPS PUB 180-1. It 2689 | produces a 20-byte output. Note that all references to SHA 2690 | actually use the modified SHA-1 algorithm. [SHA] 2692 SSL 2693 Netscape's Secure Socket Layer protocol [SSL3]. TLS is based on 2694 SSL Version 3.0 2696 stream cipher 2697 An encryption algorithm that converts a key into a 2698 cryptographically-strong keystream, which is then exclusive-ORed 2699 with the plaintext. 2701 symmetric cipher 2702 See bulk cipher. 2704 | Transport Layer Security (TLS) 2705 | This protocol; also, the Transport Layer Security working group 2706 | of the Internet Engineering Task Force (IETF). See "Comments" at 2707 | the end of this document. 2709 C. CipherSuite definitions 2711 CipherSuite Is Key Cipher Hash 2712 Exportable Exchange 2714 TLS_NULL_WITH_NULL_NULL * NULL NULL NULL 2715 TLS_RSA_WITH_NULL_MD5 * RSA NULL MD5 2716 TLS_RSA_WITH_NULL_SHA * RSA NULL SHA 2717 TLS_RSA_EXPORT_WITH_RC4_40_MD5 * RSA_EXPORT RC4_40 MD5 2718 TLS_RSA_WITH_RC4_128_MD5 RSA RC4_128 MD5 2719 TLS_RSA_WITH_RC4_128_SHA RSA RC4_128 SHA 2720 TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 * RSA_EXPORT RC2_CBC_40 MD5 2721 TLS_RSA_WITH_IDEA_CBC_SHA RSA IDEA_CBC SHA 2722 TLS_RSA_EXPORT_WITH_DES40_CBC_SHA * RSA_EXPORT DES40_CBC SHA 2723 TLS_RSA_WITH_DES_CBC_SHA RSA DES_CBC SHA 2724 TLS_RSA_WITH_3DES_EDE_CBC_SHA RSA 3DES_EDE_CBC SHA 2725 TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA * DH_DSS_EXPORT DES40_CBC SHA 2726 TLS_DH_DSS_WITH_DES_CBC_SHA DH_DSS DES_CBC SHA 2727 TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA DH_DSS 3DES_EDE_CBC SHA 2728 TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA * DH_RSA_EXPORT DES40_CBC SHA 2729 TLS_DH_RSA_WITH_DES_CBC_SHA DH_RSA DES_CBC SHA 2730 TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA DH_RSA 3DES_EDE_CBC SHA 2731 TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA * DHE_DSS_EXPORT DES40_CBC SHA 2732 TLS_DHE_DSS_WITH_DES_CBC_SHA DHE_DSS DES_CBC SHA 2733 TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE_DSS 3DES_EDE_CBC SHA 2734 TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA * DHE_RSA_EXPORT DES40_CBC SHA 2735 TLS_DHE_RSA_WITH_DES_CBC_SHA DHE_RSA DES_CBC SHA 2736 TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE_RSA 3DES_EDE_CBC SHA 2737 TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 * DH_anon_EXPORT RC4_40 MD5 2738 TLS_DH_anon_WITH_RC4_128_MD5 DH_anon RC4_128 MD5 2739 TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA DH_anon DES40_CBC SHA 2740 TLS_DH_anon_WITH_DES_CBC_SHA DH_anon DES_CBC SHA 2741 TLS_DH_anon_WITH_3DES_EDE_CBC_SHA DH_anon 3DES_EDE_CBC SHA 2743 * Indicates IsExportable is True 2745 Key 2746 Exchange 2747 Algorithm Description Key size limit 2749 DHE_DSS Ephemeral DH with DSS signatures None 2750 DHE_DSS_EXPORT Ephemeral DH with DSS signatures DH = 512 bits 2751 DHE_RSA Ephemeral DH with RSA signatures None 2752 DHE_RSA_EXPORT Ephemeral DH with RSA signatures DH = 512 bits, 2753 RSA = none 2754 DH_anon Anonymous DH, no signatures None 2755 DH_anon_EXPORT Anonymous DH, no signatures DH = 512 bits 2756 DH_DSS DH with DSS-based certificates None 2757 DH_DSS_EXPORT DH with DSS-based certificates DH = 512 bits 2758 DH_RSA DH with RSA-based certificates None 2759 DH_RSA_EXPORT DH with RSA-based certificates DH = 512 bits, 2760 RSA = none 2761 NULL No key exchange N/A 2762 RSA RSA key exchange None 2763 RSA_EXPORT RSA key exchange RSA = 512 bits 2765 Key size limit 2766 The key size limit gives the size of the largest public key that 2767 can be legally used for encryption in cipher suites that are 2768 exportable. 2770 Key Expanded Effective IV Block 2771 Cipher Type Material Key Material Key Bits Size Size 2773 NULL * Stream 0 0 0 0 N/A 2774 IDEA_CBC Block 16 16 128 8 8 2775 RC2_CBC_40 * Block 5 16 40 8 8 2776 RC4_40 * Stream 5 16 40 0 N/A 2777 RC4_128 Stream 16 16 128 0 N/A 2778 DES40_CBC * Block 5 8 40 8 8 2779 DES_CBC Block 8 8 56 8 8 2780 3DES_EDE_CBC Block 24 24 168 8 8 2782 * Indicates IsExportable is true. 2784 Key Material 2785 The number of bytes from the key_block that are used for 2786 generating the write keys. 2788 Expanded Key Material 2789 The number of bytes actually fed into the encryption algorithm 2791 Effective Key Bits 2792 How much entropy material is in the key material being fed into 2793 the encryption routines. 2795 Hash Hash Padding 2796 function Size Size 2797 NULL 0 0 2798 MD5 16 48 2799 SHA 20 40 2801 Appendix D 2803 D. Implementation Notes 2805 The TLS protocol cannot prevent many common security mistakes. This 2806 section provides several recommendations to assist implementers. 2808 D.1. Temporary RSA keys 2810 US Export restrictions limit RSA keys used for encryption to 512 2811 bits, but do not place any limit on lengths of RSA keys used for 2812 signing operations. Certificates often need to be larger than 512 2813 bits, since 512-bit RSA keys are not secure enough for high-value 2814 transactions or for applications requiring long-term security. Some 2815 certificates are also designated signing-only, in which case they 2816 cannot be used for key exchange. 2818 When the public key in the certificate cannot be used for 2819 encryption, the server signs a temporary RSA key, which is then 2820 exchanged. In exportable applications, the temporary RSA key should 2821 be the maximum allowable length (i.e., 512 bits). Because 512-bit 2822 RSA keys are relatively insecure, they should be changed often. For 2823 typical electronic commerce applications, it is suggested that keys 2824 be changed daily or every 500 transactions, and more often if 2825 possible. Note that while it is acceptable to use the same temporary 2826 key for multiple transactions, it must be signed each time it is 2827 used. 2829 RSA key generation is a time-consuming process. In many cases, a 2830 low-priority process can be assigned the task of key generation. 2832 Whenever a new key is completed, the existing temporary key can be 2833 replaced with the new one. 2835 D.2. Random Number Generation and Seeding 2837 TLS requires a cryptographically-secure pseudorandom number 2838 generator (PRNG). Care must be taken in designing and seeding PRNGs. 2839 PRNGs based on secure hash operations, most notably MD5 and/or SHA, 2840 are acceptable, but cannot provide more security than the size of 2841 the random number generator state. (For example, MD5-based PRNGs 2842 usually provide 128 bits of state.) 2844 To estimate the amount of seed material being produced, add the 2845 number of bits of unpredictable information in each seed byte. For 2846 example, keystroke timing values taken from a PC compatible's 18.2 2847 Hz timer provide 1 or 2 secure bits each, even though the total size 2848 of the counter value is 16 bits or more. To seed a 128-bit PRNG, one 2849 would thus require approximately 100 such timer values. 2851 Warning: The seeding functions in RSAREF and versions of BSAFE prior to 2852 3.0 are order-independent. For example, if 1000 seed bits are 2853 supplied, one at a time, in 1000 separate calls to the seed 2854 function, the PRNG will end up in a state which depends only 2855 on the number of 0 or 1 seed bits in the seed data (i.e., 2856 there are 1001 possible final states). Applications using 2857 BSAFE or RSAREF must take extra care to ensure proper seeding. 2858 | This may be accomplished by accumulating seed bits into a 2859 | buffer and processing them all at once or by processing an 2860 | incrementing counter with every seed bit; either method will 2861 | reintroduce order dependance into the seeding process. 2863 D.3. Certificates and authentication 2865 Implementations are responsible for verifying the integrity of 2866 certificates and should generally support certificate revocation 2867 messages. Certificates should always be verified to ensure proper 2868 signing by a trusted Certificate Authority (CA). The selection and 2869 addition of trusted CAs should be done very carefully. Users should 2870 be able to view information about the certificate and root CA. 2872 D.4. CipherSuites 2874 TLS supports a range of key sizes and security levels, including 2875 some which provide no or minimal security. A proper implementation 2876 will probably not support many cipher suites. For example, 40-bit 2877 encryption is easily broken, so implementations requiring strong 2878 security should not allow 40-bit keys. Similarly, anonymous 2879 Diffie-Hellman is strongly discouraged because it cannot prevent 2880 man-in-the-middle attacks. Applications should also enforce minimum 2881 and maximum key sizes. For example, certificate chains containing 2882 512-bit RSA keys or signatures are not appropriate for high-security 2883 applications. 2885 E. Backward Compatibility With SSL 2887 | For historical reasons and in order to avoid a profligate 2888 | consumption of reserved port numbers, application protocols which 2889 | are secured by TLS 1.0, SSL 3.0, and SSL 2.0 all frequently share 2890 | the same connection port: for example, the https protocol (HTTP 2891 | secured by SSL or TLS) uses port 443 regardless of which security 2892 | protocol it is using. Thus, some mechanism must be determined to 2893 | distinguish and negotiate among the various protocols. 2895 | TLS version 1.0 and SSL 3.0 are very similar; thus, supporting both 2896 | is easy. TLS clients who wish to negotiate with SSL 3.0 servers 2897 | should send client hello messages using the SSL 3.0 record format 2898 | and client hello structure, sending {3, 1} for the version field to 2899 | note that they support TLS 1.0. If the server supports only SSL 3.0, 2900 | it will respond with an SSL 3.0 server hello; if it supports TLS, 2901 | with a TLS server hello. The negotiation then proceeds as 2902 | appropriate for the negotiated protocol. 2904 | Similarly, a TLS server which wishes to interoperate with SSL 3.0 2905 | clients should accept SSL 3.0 client hello messages and respond with 2906 | an SSL 3.0 server hello if an SSL 3.0 client hello is received which 2907 | has a version field of {3, 0}, denoting that this client does not 2908 | support TLS. 2910 | Whenever a client already knows the highest protocol known to a 2911 | server (for example, when resuming a session), it should initiate 2912 | the connection in that native protocol. 2914 | TLS 1.0 clients that support SSL Version 2.0 servers must send SSL 2915 | Version 2.0 client hello messages [SSL-2]. TLS servers should accept 2916 | either client hello format if they wish to support SSL 2.0 clients 2917 | on the same connection port. The only deviations from the Version 2918 | 2.0 specification are the ability to specify a version with a value 2919 | of three and the support for more ciphering types in the CipherSpec. 2921 Warning: The ability to send Version 2.0 client hello messages will be 2922 phased out with all due haste. Implementers should make every 2923 effort to move forward as quickly as possible. Version 3.0 2924 provides better mechanisms for moving to newer versions. 2926 The following cipher specifications are carryovers from SSL Version 2927 2.0. These are assumed to use RSA for key exchange and 2928 authentication. 2930 | V2CipherSpec TLS_RC4_128_WITH_MD5 = { 0x01,0x00,0x80 }; 2931 | V2CipherSpec TLS_RC4_128_EXPORT40_WITH_MD5 = { 0x02,0x00,0x80 }; 2932 | V2CipherSpec TLS_RC2_CBC_128_CBC_WITH_MD5 = { 0x03,0x00,0x80 }; 2933 | V2CipherSpec TLS_RC2_CBC_128_CBC_EXPORT40_WITH_MD5 2934 | = { 0x04,0x00,0x80 }; 2935 | V2CipherSpec TLS_IDEA_128_CBC_WITH_MD5 = { 0x05,0x00,0x80 }; 2936 | V2CipherSpec TLS_DES_64_CBC_WITH_MD5 = { 0x06,0x00,0x40 }; 2937 | V2CipherSpec TLS_DES_192_EDE3_CBC_WITH_MD5 = { 0x07,0x00,0xC0 }; 2939 | Cipher specifications native to TLS can be included in Version 2.0 2940 | client hello messages using the syntax below. Any V2CipherSpec 2941 | element with its first byte equal to zero will be ignored by Version 2942 | 2.0 servers. Clients sending any of the above V2CipherSpecs should 2943 | also include the TLS equivalent (see Appendix A.6): 2945 | V2CipherSpec (see TLS name) = { 0x00, CipherSuite }; 2947 E.1. Version 2 client hello 2949 The Version 2.0 client hello message is presented below using this 2950 document's presentation model. The true definition is still assumed 2951 to be the SSL Version 2.0 specification. 2953 uint8 V2CipherSpec[3]; 2955 struct { 2956 unit8 msg_type; 2957 Version version; 2958 uint16 cipher_spec_length; 2959 uint16 session_id_length; 2960 uint16 challenge_length; 2961 V2CipherSpec cipher_specs[V2ClientHello.cipher_spec_length]; 2962 opaque session_id[V2ClientHello.session_id_length]; 2963 Random challenge; 2964 } V2ClientHello; 2966 msg_type 2967 This field, in conjunction with the version field, identifies a 2968 version 2 client hello message. The value should be one (1). 2970 version 2971 The highest version of the protocol supported by the client 2972 (equals ProtocolVersion.version, see Appendix A.1.1). 2974 cipher_spec_length 2975 This field is the total length of the field cipher_specs. It 2976 cannot be zero and must be a multiple of the V2CipherSpec length 2977 (3). 2979 session_id_length 2980 This field must have a value of either zero or 16. If zero, the 2981 client is creating a new session. If 16, the session_id field 2982 will contain the 16 bytes of session identification. 2984 challenge_length 2985 The length in bytes of the client's challenge to the server to 2986 authenticate itself. This value must be 32. 2988 cipher_specs 2989 This is a list of all CipherSpecs the client is willing and able 2990 to use. There must be at least one CipherSpec acceptable to the 2991 server. 2993 session_id 2994 If this field's length is not zero, it will contain the 2995 identification for a session that the client wishes to resume. 2997 challenge 2998 The client challenge to the server for the server to identify 2999 itself is a (nearly) arbitrary length random. The Version 3.0 3000 server will right justify the challenge data to become the 3001 ClientHello.random data (padded with leading zeroes, if 3002 necessary), as specified in this Version 3.0 protocol. If the 3003 length of the challenge is greater than 32 bytes, only the last 3004 32 bytes are used. It is legitimate (but not necessary) for a V3 3005 server to reject a V2 ClientHello that has fewer than 16 bytes 3006 of challenge data. 3008 |Note: Requests to resume a TLS session should use a TLS client hello. 3010 E.2. Avoiding man-in-the-middle version rollback 3012 | When TLS clients fall back to Version 2.0 compatibility mode, they 3013 | should use special PKCS #1 block formatting. This is done so that 3014 | TLS servers will reject Version 2.0 sessions with TLS-capable 3015 | clients. 3017 | When TLS clients are in Version 2.0 compatibility mode, they set the 3018 right-hand (least-significant) 8 random bytes of the PKCS padding 3019 (not including the terminal null of the padding) for the RSA 3020 encryption of the ENCRYPTED-KEY-DATA field of the CLIENT-MASTER-KEY 3021 to 0x03 (the other padding bytes are random). After decrypting the 3022 ENCRYPTED-KEY-DATA field, servers that support TLS should issue an 3023 error if these eight padding bytes are 0x03. Version 2.0 servers 3024 receiving blocks padded in this manner will proceed normally. 3026 Appendix F 3028 F. Security analysis 3030 The TLS protocol is designed to establish a secure connection 3031 between a client and a server communicating over an insecure 3032 channel. This document makes several traditional assumptions, 3033 including that attackers have substantial computational resources 3034 and cannot obtain secret information from sources outside the 3035 protocol. Attackers are assumed to have the ability to capture, 3036 modify, delete, replay, and otherwise tamper with messages sent over 3037 the communication channel. This appendix outlines how TLS has been 3038 designed to resist a variety of attacks. 3040 F.1. Handshake protocol 3042 The handshake protocol is responsible for selecting a CipherSpec and 3043 generating a Master Secret, which together comprise the primary 3044 cryptographic parameters associated with a secure session. The 3045 handshake protocol can also optionally authenticate parties who have 3046 certificates signed by a trusted certificate authority. 3048 F.1.1. Authentication and key exchange 3050 TLS supports three authentication modes: authentication of both 3051 parties, server authentication with an unauthenticated client, and 3052 total anonymity. Whenever the server is authenticated, the channel 3053 should be secure against man-in-the-middle attacks, but completely 3054 anonymous sessions are inherently vulnerable to such attacks. 3055 Anonymous servers cannot authenticate clients, since the client 3056 signature in the certificate verify message may require a server 3057 certificate to bind the signature to a particular server. If the 3058 server is authenticated, its certificate message must provide a 3059 valid certificate chain leading to an acceptable certificate 3060 authority. Similarly, authenticated clients must supply an 3061 acceptable certificate to the server. Each party is responsible for 3062 verifying that the other's certificate is valid and has not expired 3063 or been revoked. 3065 The general goal of the key exchange process is to create a 3066 pre_master_secret known to the communicating parties and not to 3067 attackers. The pre_master_secret will be used to generate the 3068 master_secret (see Section 7.1). The master_secret is required to 3069 | generate the certificate verify and finished messages, encryption 3070 keys, and MAC secrets (see Sections 6.4.8, 6.4.9 and 5.4). By 3071 sending a correct finished message, parties thus prove that they 3072 know the correct pre_master_secret. 3074 F.1.1.1. Anonymous key exchange 3076 Completely anonymous sessions can be established using RSA or 3077 Diffie-Hellman for key exchange. With anonymous RSA, the client 3078 encrypts a pre_master_secret with the server's uncertified public 3079 key extracted from the server key exchange message. The result is 3080 sent in a client key exchange message. Since eavesdroppers do not 3081 know the server's private key, it will be infeasible for them to 3082 decode the pre_master_secret. (Note that no anonymous RSA Cipher 3083 Suites are defined in this document). 3085 With Diffie-Hellman, the server's public parameters are contained in 3086 the server key exchange message and the client's are sent in the 3087 client key exchange message. Eavesdroppers who do not know the 3088 private values should not be able to find the Diffie-Hellman result 3089 (i.e. the pre_master_secret). 3091 Warning: Completely anonymous connections only provide protection 3092 against passive eavesdropping. Unless an independent 3093 tamper-proof channel is used to verify that the finished 3094 messages were not replaced by an attacker, server 3095 authentication is required in environments where active 3096 man-in-the-middle attacks are a concern. 3098 F.1.1.2. RSA key exchange and authentication 3100 With RSA, key exchange and server authentication are combined. The 3101 public key may be either contained in the server's certificate or 3102 may be a temporary RSA key sent in a server key exchange message. 3103 When temporary RSA keys are used, they are signed by the server's 3104 RSA or DSS certificate. The signature includes the current 3105 ClientHello.random, so old signatures and temporary keys cannot be 3106 replayed. Servers may use a single temporary RSA key for multiple 3107 negotiation sessions. 3109 Note: The temporary RSA key option is useful if servers need large 3110 certificates but must comply with government-imposed size limits 3111 on keys used for key exchange. 3113 After verifying the server's certificate, the client encrypts a 3114 pre_master_secret with the server's public key. By successfully 3115 decoding the pre_master_secret and producing a correct finished 3116 message, the server demonstrates that it knows the private key 3117 corresponding to the server certificate. 3119 When RSA is used for key exchange, clients are authenticated using 3120 the certificate verify message (see Section 6.4.8). The client signs 3121 a value derived from the master_secret and all preceding handshake 3122 messages. These handshake messages include the server certificate, 3123 which binds the signature to the server, and ServerHello.random, 3124 which binds the signature to the current handshake process. 3126 F.1.1.3. Diffie-Hellman key exchange with authentication 3128 When Diffie-Hellman key exchange is used, the server can either 3129 supply a certificate containing fixed Diffie-Hellman parameters or 3130 can use the server key exchange message to send a set of temporary 3131 Diffie-Hellman parameters signed with a DSS or RSA certificate. 3132 Temporary parameters are hashed with the hello.random values before 3133 signing to ensure that attackers do not replay old parameters. In 3134 either case, the client can verify the certificate or signature to 3135 ensure that the parameters belong to the server. 3137 If the client has a certificate containing fixed Diffie-Hellman 3138 parameters, its certificate contains the information required to 3139 complete the key exchange. Note that in this case the client and 3140 server will generate the same Diffie-Hellman result (i.e., 3141 pre_master_secret) every time they communicate. To prevent the 3142 pre_master_secret from staying in memory any longer than necessary, 3143 it should be converted into the master_secret as soon as possible. 3144 Client Diffie-Hellman parameters must be compatible with those 3145 supplied by the server for the key exchange to work. 3147 If the client has a standard DSS or RSA certificate or is 3148 unauthenticated, it sends a set of temporary parameters to the 3149 server in the client key exchange message, then optionally uses a 3150 certificate verify message to authenticate itself. 3152 F.1.2. Version rollback attacks 3154 Because TLS includes substantial improvements over SSL Version 2.0, 3155 attackers may try to make TLS-capable clients and servers fall back 3156 to Version 2.0. This attack can occur if (and only if) two 3157 TLS-capable parties use an SSL 2.0 handshake. 3159 Although the solution using non-random PKCS #1 block type 2 message 3160 padding is inelegant, it provides a reasonably secure way for 3161 Version 3.0 servers to detect the attack. This solution is not 3162 secure against attackers who can brute force the key and substitute 3163 a new ENCRYPTED-KEY-DATA message containing the same key (but with 3164 normal padding) before the application specified wait threshold has 3165 expired. Parties concerned about attacks of this scale should not be 3166 using 40-bit encryption keys anyway. Altering the padding of the 3167 least-significant 8 bytes of the PKCS padding does not impact 3168 | security for the size of the signed hashes and RSA key lengths used 3169 | in the protocol, since this is essentially equivalent to increasing 3170 | the input block size by 8 bytes. 3172 F.1.3. Detecting attacks against the handshake protocol 3174 An attacker might try to influence the handshake exchange to make 3175 the parties select different encryption algorithms than they would 3176 normally choose. Because many implementations will support 40-bit 3177 exportable encryption and some may even support null encryption or 3178 MAC algorithms, this attack is of particular concern. 3180 For this attack, an attacker must actively change one or more 3181 handshake messages. If this occurs, the client and server will 3182 compute different values for the handshake message hashes. As a 3183 result, the parties will not accept each others' finished messages. 3184 Without the master_secret, the attacker cannot repair the finished 3185 messages, so the attack will be discovered. 3187 F.1.4. Resuming sessions 3189 When a connection is established by resuming a session, new 3190 ClientHello.random and ServerHello.random values are hashed with the 3191 session's master_secret. Provided that the master_secret has not 3192 been compromised and that the secure hash operations used to produce 3193 the encryption keys and MAC secrets are secure, the connection 3194 should be secure and effectively independent from previous 3195 connections. Attackers cannot use known encryption keys or MAC 3196 secrets to compromise the master_secret without breaking the secure 3197 hash operations (which use both SHA and MD5). 3199 Sessions cannot be resumed unless both the client and server agree. 3200 If either party suspects that the session may have been compromised, 3201 or that certificates may have expired or been revoked, it should 3202 force a full handshake. An upper limit of 24 hours is suggested for 3203 session ID lifetimes, since an attacker who obtains a master_secret 3204 may be able to impersonate the compromised party until the 3205 corresponding session ID is retired. Applications that may be run in 3206 relatively insecure environments should not write session IDs to 3207 stable storage. 3209 F.1.5. MD5 and SHA 3211 TLS uses hash functions very conservatively. Where possible, both 3212 MD5 and SHA are used in tandem to ensure that non-catastrophic flaws 3213 in one algorithm will not break the overall protocol. 3215 F.2. Protecting application data 3217 The master_secret is hashed with the ClientHello.random and 3218 ServerHello.random to produce unique data encryption keys and MAC 3219 secrets for each connection. 3221 Outgoing data is protected with a MAC before transmission. To 3222 prevent message replay or modification attacks, the MAC is computed 3223 from the MAC secret, the sequence number, the message length, the 3224 message contents, and two fixed character strings. The message type 3225 field is necessary to ensure that messages intended for one TLS 3226 Record Layer client are not redirected to another. The sequence 3227 number ensures that attempts to delete or reorder messages will be 3228 detected. Since sequence numbers are 64-bits long, they should never 3229 overflow. Messages from one party cannot be inserted into the 3230 other's output, since they use independent MAC secrets. Similarly, 3231 the server-write and client-write keys are independent so stream 3232 cipher keys are used only once. 3234 If an attacker does break an encryption key, all messages encrypted 3235 with it can be read. Similarly, compromise of a MAC key can make 3236 message modification attacks possible. Because MACs are also 3237 encrypted, message-alteration attacks generally require breaking the 3238 encryption algorithm as well as the MAC. 3240 Note: MAC secrets may be larger than encryption keys, so messages can 3241 remain tamper resistant even if encryption keys are broken. 3243 F.3. Final notes 3245 For TLS to be able to provide a secure connection, both the client 3246 and server systems, keys, and applications must be secure. In 3247 addition, the implementation must be free of security errors. 3249 The system is only as strong as the weakest key exchange and 3250 authentication algorithm supported, and only trustworthy 3251 cryptographic functions should be used. Short public keys, 40-bit 3252 bulk encryption keys, and anonymous servers should be used with 3253 great caution. Implementations and users must be careful when 3254 deciding which certificates and certificate authorities are 3255 acceptable; a dishonest certificate authority can do tremendous 3256 damage. 3258 Appendix G 3260 G. Patent Statement 3262 This version of the TLS protocol relies on the use of patented 3263 public key encryption technology for authentication and encryption. 3264 The Internet Standards Process as defined in RFC 1310 requires a 3265 written statement from the Patent holder that a license will be made 3266 available to applicants under reasonable terms and conditions prior 3267 to approving a specification as a Proposed, Draft or Internet 3268 Standard. The Massachusetts Institute of Technology has granted RSA 3269 Data Security, Inc., exclusive sub-licensing rights to the following 3270 patent issued in the United States: 3272 Cryptographic Communications System and Method ("RSA"), No. 3273 4,405,829 3275 The Board of Trustees of the Leland Stanford Junior University have 3276 granted Caro-Kann Corporation, a wholly owned subsidiary 3277 corporation, exclusive sub-licensing rights to the following patents 3278 issued in the United States, and all of their corresponding foreign 3279 patents: 3281 Cryptographic Apparatus and Method ("Diffie-Hellman"), No. 3282 4,200,770 3284 Public Key Cryptographic Apparatus and Method 3285 ("Hellman-Merkle"), No. 4,218,582 3287 The Internet Society, Internet Architecture Board, Internet 3288 Engineering Steering Group and the Corporation for National Research 3289 Initiatives take no position on the validity or scope of the patents 3290 and patent applications, nor on the appropriateness of the terms of 3291 the assurance. The Internet Society and other groups mentioned above 3292 have not made any determination as to any other intellectual 3293 property rights which may apply to the practice of this standard. 3294 Any further consideration of these matters is the user's own 3295 responsibility. 3297 References 3299 [SSL3] Frier, Karton and Kocher, 3300 internet-draft-tls-ssl-version3-00.txt: "The SSL 3.0 Protocol", Nov 3301 18 1996. 3303 [DH1] W. Diffie and M. E. Hellman, "New Directions in Cryptography," 3304 IEEE Transactions on Information Theory, V. IT-22, n. 6, Jun 1977, 3305 pp. 74-84. 3307 [3DES] W. Tuchman, "Hellman Presents No Shortcut Solutions To DES," 3308 IEEE Spectrum, v. 16, n. 7, July 1979, pp40-41. 3310 [DES] ANSI X3.106, "American National Standard for Information 3311 Systems-Data Link Encryption," American National Standards 3312 Institute, 1983. 3314 [DSS] NIST FIPS PUB 186, "Digital Signature Standard," National 3315 Institute of Standards and Technology, U.S. Department of Commerce, 3316 18 May 1994. 3318 [FTP] J. Postel and J. Reynolds, RFC 959: File Transfer Protocol, 3319 October 1985. 3321 [HTTP] T. Berners-Lee, R. Fielding, H. Frystyk, Hypertext Transfer 3322 Protocol -- HTTP/1.0, October, 1995. 3324 [IDEA] X. Lai, "On the Design and Security of Block Ciphers," ETH 3325 Series in Information Processing, v. 1, Konstanz: Hartung-Gorre 3326 Verlag, 1992. 3328 [KRAW] H. Krawczyk, IETF Draft: Keyed-MD5 for Message 3329 Authentication, November 1995. 3331 [MD2] R. Rivest. RFC 1319: The MD2 Message Digest Algorithm. April 3332 1992. 3334 [MD5] R. Rivest. RFC 1321: The MD5 Message Digest Algorithm. April 3335 1992. 3337 [PKCS1] RSA Laboratories, "PKCS #1: RSA Encryption Standard," 3338 version 1.5, November 1993. 3340 [PKCS6] RSA Laboratories, "PKCS #6: RSA Extended Certificate Syntax 3341 Standard," version 1.5, November 1993. 3343 [PKCS7] RSA Laboratories, "PKCS #7: RSA Cryptographic Message Syntax 3344 Standard," version 1.5, November 1993. 3346 [RSA] R. Rivest, A. Shamir, and L. M. Adleman, "A Method for 3347 Obtaining Digital Signatures and Public-Key Cryptosystems," 3348 Communications of the ACM, v. 21, n. 2, Feb 1978, pp. 120-126. 3350 [RSADSI] Contact RSA Data Security, Inc., Tel: 415-595-8782 [SCH] B. 3351 Schneier. Applied Cryptography: Protocols, Algorithms, and Source 3352 Code in C, Published by John Wiley & Sons, Inc. 1994. 3354 [SHA] NIST FIPS PUB 180-1, "Secure Hash Standard," National 3355 Institute of Standards and Technology, U.S. Department of Commerce, 3356 DRAFT, 31 May 1994. 3358 [TCP] ISI for DARPA, RFC 793: Transport Control Protocol, September 3359 1981. 3361 [TEL] J. Postel and J. Reynolds, RFC 854/5, May, 1993. 3363 [X509] CCITT. Recommendation X.509: "The Directory - Authentication 3364 Framework". 1988. 3366 [XDR] R. Srinivansan, Sun Microsystems, RFC-1832: XDR: External Data 3367 Representation Standard, August 1995. 3369 Credits 3371 Working Group Chair 3373 Win Treese 3374 Open Market 3375 treeseopenmarket.com 3377 Editors 3379 Tim Dierks Christopher Allen 3380 Consensus Development Consensus Development 3381 timd@consensus.com christophera@consensus.com 3383 Authors 3385 Alan O. Freier Paul C. Kocher 3386 Netscape Communications Independent Consultant 3387 freier@netscape.com pck@netcom.com 3389 Philip L. Karlton Tim Dierks 3390 Netscape Communications Consensus Development 3391 karlton@netscape.com timd@consensus.com 3393 Other contributors 3395 Martin Abadi Robert Relyea 3396 Digital Equipment Corporation Netscape Communications 3397 ma@pa.dec.com relyea@netscape.com 3399 Taher Elgamal Jim Roskind 3400 Netscape Communications Netscape Communications 3401 elgamal@netscape.com jar@netscape.com 3403 Anil Gangolli Micheal J. Sabin, Ph. D. 3404 Netscape Communications Consulting Engineer 3405 gangolli@netscape.com msabin@netcom.com 3406 Kipp E.B. Hickman Tom Weinstein 3407 Netscape Communications Netscape Communications 3408 kipp@netscape.com tomw@netscape.com 3410 Early reviewers 3412 Robert Baldwin Clyde Monma 3413 RSA Data Security, Inc. Bellcore 3414 baldwin@rsa.com clyde@bellcore.com 3416 George Cox Eric Murray 3417 Intel Corporation ericm@lne.com 3418 cox@ibeam.jf.intel.com 3420 Cheri Dowell Avi Rubin 3421 Sun Microsystems Bellcore 3422 cheri@eng.sun.com rubin@bellcore.com 3424 Stuart Haber Don Stephenson 3425 Bellcore Sun Microsystems 3426 stuart@bellcore.com don.stephenson@eng.sun.com 3428 Burt Kaliski Joe Tardo 3429 RSA Data Security, Inc. General Magic 3430 burt@rsa.com tardo@genmagic.com 3432 Comments 3434 Comments on this draft should be sent to the editors, Tim Dierks 3435 and Christopher Allen 3436 , or to the IETF Transport Layer 3437 Security (TLS) Working Group. 3439 The discussion list for IETF-TLS is at IETF-TLS@W3.ORG. You 3440 subscribe and unsubscribe by sending to IETF-TLS-REQUEST@W3.ORG with 3441 subscribe or unsubscribe in the SUBJECT of the message. 3443 Archives of the list are at: 3444