idnits 2.17.1 draft-hickman-netscape-ssl-00.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-18) 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 the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 3 longer pages, the longest (page 9) being 525 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 26 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** 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. ** There are 161 instances of too long lines in the document, the longest one being 7 characters in excess of 72. ** There are 63 instances of lines with control characters in the document. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 947: '...ters ANY DEFINED BY ALGORITHM OPTIONAL...' Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 273 has weird spacing: '...tion of the c...' == Line 549 has weird spacing: '...ing the most...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: '0' is mentioned on line 922, but not defined -- Looks like a reference, but probably isn't: 'MAC-SIZE' on line 134 -- Looks like a reference, but probably isn't: 'N' on line 135 -- Looks like a reference, but probably isn't: 'PADDING' on line 136 -- Looks like a reference, but probably isn't: 'SECRET-LENGTH' on line 510 -- Looks like a reference, but probably isn't: '0-15' on line 548 -- Looks like a reference, but probably isn't: '0-7' on line 592 -- Looks like a reference, but probably isn't: '8-15' on line 593 -- Looks like a reference, but probably isn't: 'N-1' on line 844 -- Looks like a reference, but probably isn't: 'N-2' on line 864 == Unused Reference: '4' is defined on line 1377, but no explicit reference was found in the text == Unused Reference: '6' is defined on line 1383, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. '1' -- Possible downref: Non-RFC (?) normative reference: ref. '2' -- Possible downref: Non-RFC (?) normative reference: ref. '3' -- Possible downref: Non-RFC (?) normative reference: ref. '4' -- Possible downref: Non-RFC (?) normative reference: ref. '5' -- Possible downref: Non-RFC (?) normative reference: ref. '6' ** Downref: Normative reference to an Informational RFC: RFC 1321 (ref. '7') ** Obsolete normative reference: RFC 1319 (ref. '8') (Obsoleted by RFC 6149) -- Possible downref: Non-RFC (?) normative reference: ref. '9' -- Possible downref: Non-RFC (?) normative reference: ref. '10' Summary: 13 errors (**), 0 flaws (~~), 8 warnings (==), 20 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Kipp E.B. Hickman 3 Internet Draft Netscape Communications Corp 4 April 1995 (Expires 10/95) 6 The SSL Protocol 7 9 1. STATUS OF THIS MEMO 11 This document is an Internet-Draft.Internet-Drafts are working documents 12 of the Internet Engineering Task Force (IETF), its areas, and its working 13 groups. Note that other groups may also distribute working documents as 14 Internet-Drafts. 16 Internet-Drafts are draft documents valid for a maximum of six months 17 and may be updated, replaced, or obsoleted by other documents at any 18 time. It is inappropriate to use Internet-Drafts as reference material or to 19 cite them other than as "work in progress." 21 To learn the current status of any Internet-Draft, please check the "1id- 22 abstracts.txt" listing contained in the Internet- Drafts Shadow Directories 23 on ds.internic.net (US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US 24 West Coast), or munnari.oz.au (Pacific Rim). 25 2. ABSTRACT 27 This document specifies the Secure Sockets Layer (SSL) protocol, a 28 security protocol that provides privacy over the Internet. The protocol 29 allows client/server applications to communicate in a way that cannot be 30 eavesdropped. Server's are always authenticated and clients are optionally 31 authenticated. 33 3. INTRODUCTION 35 The SSL Protocol is designed to provide privacy between two 36 communicating applications (a client and a server). Second, the protocol is 37 designed to authenticate the server, and optionally the client. SSL requires 38 a reliable transport protocol (e.g. TCP) for data transmission and 39 reception. 41 The advantage of the SSL Protocol is that it is application protocol 42 independent. A "higher level" application protocol (e.g. HTTP, FTP, 43 TELNET, etc.) can layer on top of the SSL Protocol transparently. The 44 SSL Protocol can negotiate an encryption algorithm and session key as 45 well as authenticate a server before the application protocol transmits or 46 receives its first byte of data. All of the application protocol data is 47 transmitted encrypted, ensuring privacy. 49 The SSL protocol provides "channel security" which has three basic 50 properties: 52 The channel is private. Encryption is used for all messages after a 53 simple handshake is used to define a secret key. Symmetric 54 cryptography is used for data encryption (e.g. DES, RC4, etc.) 56 The channel is authenticated. The server endpoint of the conversation 57 is always authenticated, while the client endpoint is optionally 58 authenticated. Asymmetric cryptography is used for authentication 60 Hickman [page 1] 62 (e.g. Public Key Cryptography). 64 The channel is reliable. The message transport includes a message 65 integrity check (using a MAC). Secure hash functions (e.g. MD2, 66 MD5) are used for MAC computations. 68 The SSL protocol is actually composed of two protocols. At the lowest 69 level, layered on top of some reliable transport protocol, is the "SSL 70 Record Protocol". The SSL Record Protocol is used for encapsulation of 71 all transmitted and received data, including the SSL Handshake Protocol, 72 which is used to establish security parameters. 73 4. SSL Record Protocol Specification 75 4.1 SSL Record Header Format 77 In SSL, all data sent is encapsulated in a record, an object which is 78 composed of a header and some non-zero amount of data. Each record 79 header contains a two or three byte length code. If the most significant bit 80 is set in the first byte of the record length code then the record has no 81 padding and the total header length will be 2 bytes, otherwise the record 82 has padding and the total header length will be 3 bytes. The record header 83 is transmitted before the data portion of the record. 85 Note that in the long header case (3 bytes total), the second most 86 significant bit in the first byte has special meaning. When zero, the record 87 being sent is a data record. When one, the record being sent is a security 88 escape (there are currently no examples of security escapes; this is 89 reserved for future versions of the protocol). In either case, the length code 90 describes how much data is in the record. 92 The record length code does not include the number of bytes consumed by 93 the record header (2 or 3). For the 2 byte header, the record length is 94 computed by (using a "C"-like notation): 96 RECORD-LENGTH = ((byte[0] & 0x7f) << 8)) | byte[1]; 98 Where byte[0] represents the first byte received and byte[1] the second 99 byte received. When the 3 byte header is used, the record length is 100 computed as follows (using a "C"-like notation): 102 RECORD-LENGTH = ((byte[0] & 0x3f) << 8)) | byte[1]; 103 IS-ESCAPE = (byte[0] & 0x40) != 0; 104 PADDING = byte[2]; 106 The record header defines a value called PADDING. The PADDING 107 value specifies how many bytes of data were appended to the original 108 record by the sender. The padding data is used to make the record length 109 be a multiple of the block ciphers block size when a block cipher is used 110 for encryption. 112 The sender of a "padded" record appends the padding data to the end of its 113 normal data and then encrypts the total amount (which is now a multiple 114 of the block cipher's block size). The actual value of the padding data is 115 unimportant, but the encrypted form of it must be transmitted for the 116 receiver to properly decrypt the record. Once the total amount being 118 Hickman [page 2] 120 transmitted is known the header can be properly constructed with the 121 PADDING value set appropriately. 123 The receiver of a padded record decrypts the entire record data (sans 124 record length and the optional padding) to get the clear data, then subtracts 125 the PADDING value from the RECORD-LENGTH to determine the 126 final RECORD-LENGTH. The clear form of the padding data must be 127 discarded. 129 4.1.1 SSL Record Data Format 131 The data portion of an SSL record is composed of three components 132 (transmitted and received in the order shown): 134 MAC-DATA[MAC-SIZE] 135 ACTUAL-DATA[N] 136 PADDING-DATA[PADDING] 138 ACTUAL-DATA is the actual data being transmitted (the message 139 payload). PADDING-DATA is the padding data sent when a block cipher 140 is used and padding is needed. Finally, MAC-DATA is the "Message 141 Authentication Code". 143 When SSL records are sent in the clear, no cipher is used.Consequently the 144 amount of PADDING-DATA will be zero and the amount of MAC- 145 DATA will be zero. When encryption is in effect, the PADDING-DATA 146 will be a function of the cipher block size. The MAC-DATA is a function 147 of the CIPHER-CHOICE (more about that later). 149 The MAC-DATA is computed as follows: 151 MAC-DATA = HASH[ SECRET, ACTUAL-DATA, PADDING-DATA, 152 SEQUENCE-NUMBER ] 154 Where the SECRET data is fed to the hash function first, followed by the 155 ACTUAL-DATA, which is followed by the PADDING-DATA which is 156 finally followed by the SEQUENCE-NUMBER. The SEQUENCE- 157 NUMBER is a 32 bit value which is presented to the hash function as four 158 bytes, with the first byte being the most significant byte of the sequence 159 number, the second byte being the next most significant byte of the 160 sequence number, the third byte being the third most significant byte, and 161 the fourth byte being the least significant byte (that is, in network byte 162 order or "big endian" order). 164 MAC-SIZE is a function of the digest algorithm being used. For MD2 and 165 MD5 the MAC-SIZE will be 16 bytes (128 bits). 167 The SECRET value is a function of which party is sending the message. If 168 the client is sending the message then the SECRET is the CLIENT- 169 WRITE-KEY (the server will use the SERVER-READ-KEY to verify 170 the MAC). If the client is receiving the message then the SECRET is the 171 CLIENT-READ-KEY (the server will use the SERVER-WRITE-KEY 172 to 173 generate the MAC). 175 Hickman [page 3] 177 The SEQUENCE-NUMBER is a counter which is incremented by both 178 the sender and the receiver. For each transmission direction, a pair of 179 counters is kept (one by the sender, one by the receiver). Every time a 180 message is sent by a sender the counter is incremented. Sequence numbers 181 are 32 bit unsigned quantities and must wrap to zero after incrementing 182 past 0xFFFFFFFF. 184 The receiver of a message uses the expected value of the sequence number 185 as input into the MAC HASH function (the HASH function is chosen from 186 the CIPHER-CHOICE). The computed MAC-DATA must agree bit for 187 bit with the transmitted MAC-DATA. If the comparison is not identity 188 then the record is considered damaged, and it is to be treated as if an "I/O 189 Error" had occurred (i.e. an unrecoverable error is asserted and the 190 connection is closed). 192 A final consistency check is done when a block cipher is used and the 193 protocol is using encryption. The amount of data present in a record 194 (RECORD-LENGTH))must be a multiple of the cipher's block size. If 195 the received record is not a multiple of the cipher's block size then the 196 record is considered damaged, and it is to be treated as if an "I/O Error" 197 had occurred (i.e. an unrecoverable error is asserted and the connection is 198 closed). 200 The SSL Record Layer is used for all SSL communications, including 201 handshake messages, security escapes and application data transfers. The 202 SSL Record Layer is used by both the client and the server at all times. 204 For a two byte header, the maximum record length is 32767 bytes. For the 205 three byte header, the maximum record length is 16383 bytes. The SSL 206 Handshake Protocol messages are constrained to fit in a single SSL Record 207 Protocol record. Application protocol messages are allowed to consume 208 multiple SSL Record Protocol record's. 210 Before the first record is sent using SSL all sequence numbers are 211 initialized to zero. The transmit sequence number is incremented after 212 every message sent, starting with the CLIENT-HELLO and SERVER- 213 HELLO messages. 215 5. SSL Handshake Protocol Specification 217 5.1 SSL Handshake Protocol Flow 219 The SSL Handshake Protocol is used to negotiate security enhancements 220 to data sent using the SSL Record Protocol. The security enhancements 221 consist of authentication, symmetric encryption, and message integrity. 223 The SSL Handshake Protocol has two major phases. The first phase is 224 used to establish private communications. The second phase is used for 225 client authentication. 227 5.1.1 Phase 1 229 The first phase is the initial connection phase where both parties 230 communicate their "hello" messages. The client initiates the conversation 231 by sending the CLIENT-HELLO message. The server receives the 233 Hickman [page 4] 235 CLIENT-HELLO message and processes it responding with the 236 SERVER-HELLO message. 238 At this point both the client and server have enough information to know 239 whether or not a new "master key" is needed (The master key is used for 240 production of the symmetric encryption session keys). When a new master 241 key is not needed, both the client and the server proceed immediately to 242 phase 2. 244 When a new master key is needed, the SERVER-HELLO message will 245 contain enough information for the client to generate it. This includes the 246 server's signed certificate (more about that later), a list of bulk cipher 247 specifications (see below), and a connection-id (a connection-id is a 248 randomly generated value generated by the server that is used by the client 249 and server during a single connection). The client generates the master key 250 and responds with a CLIENT-MASTER-KEY message (or an ERROR 251 message if the server information indicates that the client and server 252 cannot agree on a bulk cipher). 254 It should be noted here that each SSL endpoint uses a pair of ciphers per 255 connection (for a total of four ciphers). At each endpoint, one cipher is 256 used for outgoing communications, and one is used for incoming 257 communications. When the client or server generate a session key, they 258 actually generate two keys, the SERVER-READ-KEY (also known as the 259 CLIENT-WRITE-KEY) and the SERVER-WRITE-KEY (also known 260 as the CLIENT-READ-KEY). The master key is used by the client and 261 server to generate the various session keys (more about that later). 263 Finally, the server sends a SERVER-VERIFY message to the client after 264 the master key has been determined. This final step authenticates the 265 server, because only a server which has the appropriate public key can 266 know the master key. 268 5.1.2 Phase 2 270 The second phase is the client authentication phase. The server has already 271 been authenticated by the client in the first phase, so this phase is primarily 272 used to authenticate the client. In a typical scenario, the server will require 273 authentication of the client and send a REQUEST-CERTIFICATE 274 message. The client will answer in the positive if it has the needed 275 information, or send an ERROR message if it does not. This protocol 276 specification does not define the semantics of an ERROR response to a 277 server request (e.g., an implementation can ignore the error, close the 278 connection, etc. and still conform to this specification). In addition, it is 279 permissable for a server to cache client authentication information with the 280 "session-id" cache. The server is not required to re-authenticate the client 281 on every connection. 283 When a party is done authenticating the other party, it sends its finished 284 message. For the client, the CLIENT-FINISHED message contains the 285 encrypted form of the CONNECTION-ID for the server to verify. If the 286 verification fails, the server sends an ERROR message. 288 Once a party has sent its finished message it must continue to listen to its 289 peers messages until it too receives a finished message. Once a party has 291 Hickman [page 5] 293 both sent a finished message and received its peers finished message, the 294 SSL handshake protocol is done. At this point the application protocol 295 begins to operate (Note: the application protocol continues to be layered 296 on the SSL Record Protocol). 298 5.2 Typical Protocol Message Flow 300 The following sequences define several typical protocol message flows for 301 the SSL Handshake Protocol. In these examples we have two principals in 302 the conversation: the client and the server. We use a notation commonly 303 found in the literature [10]. When something is enclosed in curly braces 304 "{something}key" then the something has been encrypted using "key". 306 5.2.1 Assuming no session-identifier 308 client-hello C -> S: challenge, cipher_specs 309 server-hello S -> C: connection-id, server_certificate, 310 cipher_specs 311 client-master-key C -> S: {master_key}server_public_key 312 client-finish C -> S: {connection-id}client_write_key 313 server-verify S -> C: {challenge}server_write_key 314 server-finish S -> C: {new_session_id}server_write_key 316 5.2.2 Assuming a session-identifier was found by both client & server 318 client-hello C -> S: challenge, session_id, cipher_specs 319 server-hello S -> C: connection-id, session_id_hit 320 client-finish C -> S: {connection-id}client_write_key 321 server-verify S -> C: {challenge}server_write_key 322 server-finish S -> C: {session_id}server_write_key 324 5.2.3 Assuming a session-identifier was used and client authentication 325 is used 327 client-hello C -> S: challenge, session_id, cipher_specs 328 server-hello S -> C: connection-id, session_id_hit 329 client-finish C -> S: {connection-id}client_write_key 330 server-verify S -> C: {challenge}server_write_key 331 request-certificate S -> C: {auth_type,challenge'} 332 server_write_key 333 client-certificate C -> S: {cert_type,client_cert, 334 response_data}client_write_key 335 server-finish S -> C: {session_id}server_write_key 337 In this last exchange, the response_data is a function of the auth_type. 339 5.3 Errors 341 Error handling in the SSL connection protocol is very simple. When an 342 error is detected, the detecting party sends a message to the other party. 343 Errors that are not recoverable cause the client and server to abort the 344 secure connection. Servers and client are required to "forget" any session- 345 identifiers associated with a failing connection. 347 The SSL Handshake Protocol defines the following errors: 349 Hickman [page 6] 351 NO-CIPHER-ERROR 352 This error is returned by the client to the server when it cannot find 353 a cipher or key size that it supports that is also supported by the 354 server. This error is not recoverable. 356 NO-CERTIFICATE-ERROR 357 When a REQUEST-CERTIFICATE message is sent, this error may 358 be returned if the client has no certificate to reply with. This error 359 is recoverable (for client authentication only). 361 BAD-CERTIFICATE-ERROR 362 This error is returned when a certificate is deemed bad by the 363 receiving party. Bad means that either the signature of the 364 certificate was bad or that the values in the certificate were 365 inappropriate (e.g. a name in the certificate did not match the 366 expected name). This error is recoverable (for client authentication 367 only). 369 UNSUPPORTED-CERTIFICATE-TYPE-ERROR 370 This error is returned when a client/server receives a certificate 371 type that it can't support. This error is recoverable (for client 372 authentication only). 374 5.4 SSL Handshake Protocol Messages 376 The SSL Handshake Protocol messages are encapsulated using the SSL 377 Record Protocol and are composed of two parts: a single byte message 378 type code, and some data. The client and server exchange messages until 379 both ends have sent their "finished" message, indicating that they are 380 satisfied with the SSL Handshake Protocol conversation. While one end 381 may be finished, the other may not, therefore the finished end must 382 continue to receive SSL Handshake Protocol messages until it receives a 383 "finished" message from its peer. 385 After the pair of session keys has been determined by each party, the 386 message bodies are encrypted. For the client, this happens after it verifies 387 the session-identifier or creates a new master key and has sent it to the 388 server. For the server, this happens after the session-identifier is found to 389 be good, or the server receives the client's master key message. 391 The following notation is used for SSLHP messages: 393 char MSG-EXAMPLE 394 char FIELD1 395 char FIELD2 396 char THING-MSB 397 char THING-LSB 398 char THING-DATA[(MSB<<8)|LSB]; 399 ... 401 This notation defines the data in the protocol message, including the 402 message type code. The order is presented top to bottom, with the top most 403 element being transmitted first, and the bottom most element transferred 404 last. 406 Hickman [page 7] 408 For the "THING-DATA" entry, the MSB and LSB values are actually 409 THING-MSB and THING-LSB (respectively) and define the number of 410 bytes of data actually present in the message. For example, if THING- 411 MSB were zero and THING-LSB were 8 then the THING-DATA array 412 would be exactly 8 bytes long. This shorthand is used below. 414 Length codes are unsigned values, and when the MSB and LSB are 415 combined the result is an unsigned value. Unless otherwise specified 416 lengths values are "length in bytes". 418 5.5 Client Only Protocol Messages 420 There are several messages that are only generated by clients. These 421 messages are never generated by correctly functioning servers. A client 422 receiving such a message closes the connection to the server and returns an 423 error status to the application through some unspecified mechanism. 425 5.5.1 CLIENT-HELLO (Phase 1; Sent in the clear) 427 char MSG-CLIENT-HELLO 428 char CLIENT-VERSION-MSB 429 char CLIENT-VERSION-LSB 430 char CIPHER-SPECS-LENGTH-MSB 431 char CIPHER-SPECS-LENGTH-LSB 432 char SESSION-ID-LENGTH-MSB 433 char SESSION-ID-LENGTH-LSB 434 char CHALLENGE-LENGTH-MSB 435 char CHALLENGE-LENGTH-LSB 436 char CIPHER-SPECS-DATA[(MSB<<8)|LSB] 437 char SESSION-ID-DATA[(MSB<<8)|LSB] 438 char CHALLENGE-DATA[(MSB<<8)|LSB] 440 When a client first connects to a server it is required to send the CLIENT- 441 HELLO message. The server is expecting this message from the client as 442 its first message. It is an error for a client to send anything else as its 443 first 444 message. 446 The client sends to the server its SSL version, its cipher specs (see below), 447 some challenge data, and the session-identifier data. The session-identifier 448 data is only sent if the client found a session-identifier in its cache for the 449 server, and the SESSION-ID-LENGTH will be non-zero. When there is 450 no session-identifier for the server SESSION-ID-LENGTH must be zero. 451 The challenge data is used to authenticate the server. After the client and 452 server agree on a pair of session keys, the server returns a SERVER- 453 VERIFY message with the encrypted form of the CHALLENGE-DATA. 455 Also note that the server will not send its SERVER-HELLO message 456 until it has received the CLIENT-HELLO message. This is done so that 457 the server can indicate the status of the client's session-identifier back to 458 the client in the server's first message (i.e. to increase protocol efficiency 459 and reduce the number of round trips required). 461 The server examines the CLIENT-HELLO message and will verify that it 462 can support the client version and one of the client cipher specs. The 463 server can optionally edit the cipher specs, removing any entries it doesn't 465 Hickman [page 8] 467 choose to support. The edited version will be returned in the SERVER- 468 HELLO message if the session-identifier is not in the server's cache. 470 The CIPHER-SPECS-LENGTH must be greater than zero and a 471 multiple of 3. The SESSION-ID-LENGTH must either be zero or 16. 472 The CHALLENGE-LENGTH must be greater than or equal to 16 and 473 less than or equal to 32. 475 This message must be the first message sent by the client to the server. 476 After the message is sent the client waits for a SERVER-HELLO 477 message. Any other message returned by the server (other than ERROR) 478 is disallowed. 480 5.5.2 CLIENT-MASTER-KEY (Phase 1; Sent primarily in the clear) 482 char MSG-CLIENT-MASTER-KEY 483 char CIPHER-KIND[3] 484 char CLEAR-KEY-LENGTH-MSB 485 char CLEAR-KEY-LENGTH-LSB 486 char ENCRYPTED-KEY-LENGTH-MSB 487 char ENCRYPTED-KEY-LENGTH-LSB 488 char KEY-ARG-LENGTH-MSB 489 char KEY-ARG-LENGTH-LSB 490 char CLEAR-KEY-DATA[MSB<<8|LSB] 491 char ENCRYPTED-KEY-DATA[MSB<<8|LSB] 492 char KEY-ARG-DATA[MSB<<8|LSB] 494 The client sends this message when it has determined a master key for the 495 server to use. Note that when a session-identifier has been agreed upon, 496 this message is not sent. 498 The CIPHER-KIND field indicates which cipher was chosen from the 499 server's CIPHER-SPECS. 501 The CLEAR-KEY-DATA contains the clear portion of the MASTER- 502 KEY. The CLEAR-KEY-DATA is combined with the SECRET-KEY- 503 DATA (described shortly) to form the MASTER-KEY, with the 504 SECRET-KEY-DATA being the least significant bytes of the final 505 MASTER-KEY. The ENCRYPTED-KEY-DATA contains the secret 506 portions of the MASTER-KEY, encrypted using the server's public key. 507 The encryption block is formatted using block type 2 from PKCS#1 [5]. 508 The data portion of the block is formatted as follows: 510 char SECRET-KEY-DATA[SECRET-LENGTH] 512 SECRET-LENGTH is the number of bytes of each session key that is 513 being transmitted encrypted. The SECRET-LENGTH plus the CLEAR- 514 KEY-LENGTH equals the number of bytes present in the cipher key (as 515 defined by the CIPHER-KIND). It is an error if the SECRET-LENGTH 516 found after decrypting the PKCS#1 formatted encryption block doesn't 517 match the expected value. It is also an error if CLEAR-KEY-LENGTH is 518 non-zero and the CIPHER-KIND is not an export cipher. 520 If the key algorithm needs an argument (for example, DES-CBC's 521 initialization vector) then the KEY-ARG-LENGTH fields will be non- 523 zero and the KEY-ARG-DATA will contain the relevant data. For the 524 SSL_CK_RC2_128_CBC_WITH_MD5, 525 SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5, 526 SSL_CK_IDEA_128_CBC_WITH_MD5, 527 SSL_CK_DES_64_CBC_WITH_MD5 and 528 SSL_CK_DES_192_EDE3_CBC_WITH_MD5 algorithms the KEY-ARG 529 data must be present and be exactly 8 bytes long. 531 Client and server session key production is a function of the CIPHER- 532 CHOICE: 534 SSL_CK_RC4_128_WITH_MD5 535 SSL_CK_RC4_128_EXPORT40_WITH_MD5 536 SSL_CK_RC2_128_CBC_WITH_MD5 537 SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5 538 SSL_CK_IDEA_128_CBC_WITH_MD5 540 KEY-MATERIAL-0 = MD5[ MASTER-KEY, "0", CHALLENGE, 541 CONNECTION-ID ] 542 KEY-MATERIAL-1 = MD5[ MASTER-KEY, "1", CHALLENGE, 543 CONNECTION-ID ] 545 CLIENT-READ-KEY = KEY-MATERIAL-0[0-15] 546 CLIENT-WRITE-KEY = KEY-MATERIAL-1[0-15] 548 Where KEY-MATERIAL-0[0-15] means the first 16 bytes of the KEY- 549 MATERIAL-0 data, with KEY-MATERIAL-0[0] becoming the most 550 significant byte of the CLIENT-READ-KEY. 552 Data is fed to the MD5 hash function in the order shown, from left to 553 right: first the MASTER-KEY, then the "0" or "1", then the 554 CHALLENGE and then finally the CONNECTION-ID. 556 Note that the "0" means the ascii zero character (0x30), not a zero value. 557 "1" means the ascii 1 character (0x31). MD5 produces 128 bits of output 558 data which are used directly as the key to the cipher algorithm (The most 559 significant byte of the MD5 output becomes the most significant byte of 560 the key material). 562 SSL_CK_DES_64_CBC_WITH_MD5 564 KEY-MATERIAL-0 = MD5[ MASTER-KEY, CHALLENGE, 565 CONNECTION-ID ] 567 CLIENT-READ-KEY = KEY-MATERIAL-0[0-7] 568 CLIENT-WRITE-KEY = KEY-MATERIAL-0[8-15] 570 For DES-CBC, a single 16 bytes of key material are produced using MD5. 571 The first 8 bytes of the MD5 digest are used as the CLIENT-READ-KEY 572 while the remaining 8 bytes are used as the CLIENT-WRITE-KEY. The 573 initialization vector is provided in the KEY-ARG-DATA. Note that the 574 raw key data is not parity adjusted and that this step must be performed 575 before the keys are legitimate DES keys. 577 SSL_CK_DES_192_EDE3_CBC_WITH_MD5 579 Hickman [page 10] 581 KEY-MATERIAL-0 = MD5[ MASTER-KEY, "0", CHALLENGE, 582 CONNECTION-ID ] 583 KEY-MATERIAL-1 = MD5[ MASTER-KEY, "1", CHALLENGE, 584 CONNECTION-ID ] 585 KEY-MATERIAL-2 = MD5[ MASTER-KEY, "2", CHALLENGE, 586 CONNECTION-ID ] 588 CLIENT-READ-KEY-0 = KEY-MATERIAL-0[0-7] 589 CLIENT-READ-KEY-1 = KEY-MATERIAL-0[8-15] 590 CLIENT-READ-KEY-2 = KEY-MATERIAL-1[0-7] 591 CLIENT-WRITE-KEY-0 = KEY-MATERIAL-1[8-15] 592 CLIENT-WRITE-KEY-1 = KEY-MATERIAL-2[0-7] 593 CLIENT-WRITE-KEY-2 = KEY-MATERIAL-2[8-15] 595 Data is fed to the MD5 hash function in the order shown, from left to 596 right: first the MASTER-KEY, then the "0", "1" or "2", then the 597 CHALLENGE and then finally the CONNECTION-ID. Note that the 598 "0" means the ascii zero character (0x30), not a zero value. "1" means the 599 ascii 1 character (0x31). "2" means the ascii 2 character (0x32). 601 A total of 6 keys are produced, 3 for the read side DES-EDE3 cipher and 3 602 for the write side DES-EDE3 function. The initialization vector is 603 provided in the KEY-ARG-DATA. The keys that are produced are not 604 parity adjusted. This step must be performed before proper DES keys are 605 usable. 607 Recall that the MASTER-KEY is given to the server in the CLIENT- 608 MASTER-KEY message. The CHALLENGE is given to the server by 609 the client in the CLIENT-HELLO message. The CONNECTION-ID is 610 given to the client by the server in the SERVER-HELLO message. This 611 makes the resulting cipher keys a function of the original session and the 612 current session. Note that the master key is never directly used to encrypt 613 data, and therefore cannot be easily discovered. 615 The CLIENT-MASTER-KEY message must be sent after the CLIENT- 616 HELLO message and before the CLIENT-FINISHED message. The 617 CLIENT-MASTER-KEY message must be sent if the SERVER- 618 HELLO message contains a SESSION-ID-HIT value of 0. 620 5.5.3 CLIENT-CERTIFICATE (Phase 2; Sent encrypted) 622 char MSG-CLIENT-CERTIFICATE 623 char CERTIFICATE-TYPE 624 char CERTIFICATE-LENGTH-MSB 625 char CERTIFICATE-LENGTH-LSB 626 char RESPONSE-LENGTH-MSB 627 char RESPONSE-LENGTH-LSB 628 char CERTIFICATE-DATA[MSB<<8|LSB] 629 char RESPONSE-DATA[MSB<<8|LSB] 631 This message is sent by one an SSL client in response to a server 632 REQUEST-CERTIFICATE message. The CERTIFICATE-DATA 633 contains data defined by the CERTIFICATE-TYPE value. An ERROR 634 message is sent with error code NO-CERTIFICATE-ERROR when this 635 request cannot be answered properly (e.g. the receiver of the message has 637 no registered certificate). 639 CERTIFICATE-TYPE is one of: 641 SSL_X509_CERTIFICATE 642 The CERTIFICATE-DATA contains an X.509 (1988) [3] signed 643 certificate. 645 The RESPONSE-DATA contains the authentication response data. This 646 data is a function of the AUTHENTICATION-TYPE value sent by the 647 server. 649 When AUTHENTICATION-TYPE is 650 SSL_AT_MD5_WITH_RSA_ENCRYPTION then the RESPONSE- 651 DATA contains a digital signature of the following components (in the 652 order shown): 654 the KEY-MATERIAL-0 655 the KEY-MATERIAL-1 (only if defined by the cipher kind) 656 the KEY-MATERIAL-2 (only if defined by the cipher kind) 657 the CERTIFICATE-CHALLENGE-DATA (from the 658 REQUEST-CERTIFICATE message) 659 the server's signed certificate (from the SERVER-HELLO 660 message) 662 The digital signature is constructed using MD5 and then encrypted using 663 the clients private key, formatted according to PKCS#1's digital signature 664 standard [5]. The server authenticates the client by verifying the digital 665 signature using standard techniques. Note that other digest functions are 666 supported. Either a new AUTHENTICATION-TYPE can be added, or 667 the algorithm-id in the digital signature can be changed. 669 This message must be sent by the client only in response to a REQUEST- 670 CERTIFICATE message. 672 5.5.4 CLIENT-FINISHED (Phase 2; Sent encrypted) 674 char MSG-CLIENT-FINISHED 675 char CONNECTION-ID[N-1] 677 The client sends this message when it is satisfied with the server. Note that 678 the client must continue to listen for server messages until it receives a 679 SERVER-FINISHED message. The CONNECTION-ID data is the 680 original connection-identifier the server sent with its SERVER-HELLO 681 message, encrypted using the agreed upon session key. 683 "N" is the number of bytes in the message that was sent, so "N-1" is the 684 number of bytes in the message without the message header byte. 686 For version 2 of the protocol, the client must send this message after it has 687 received the SERVER-HELLO message. If the SERVER-HELLO 688 message SESSION-ID-HIT flag is non-zero then the CLIENT- 689 FINISHED message is sent immediately, otherwise the CLIENT- 690 FINISHED message is sent after the CLIENT-MASTER-KEY message. 692 5.6 Server Only Protocol Messages 694 There are several messages that are only generated by servers. The 695 messages are never generated by correctly functioning clients. 697 5.6.1 SERVER-HELLO (Phase 1; Sent in the clear) 699 char MSG-SERVER-HELLO 700 char SESSION-ID-HIT 701 char CERTIFICATE-TYPE 702 char SERVER-VERSION-MSB 703 char SERVER-VERSION-LSB 704 char CERTIFICATE-LENGTH-MSB 705 char CERTIFICATE-LENGTH-LSB 706 char CIPHER-SPECS-LENGTH-MSB 707 char CIPHER-SPECS-LENGTH-LSB 708 char CONNECTION-ID-LENGTH-MSB 709 char CONNECTION-ID-LENGTH-LSB 710 char CERTIFICATE-DATA[MSB<<8|LSB] 711 char CIPHER-SPECS-DATA[MSB<<8|LSB] 712 char CONNECTION-ID-DATA[MSB<<8|LSB] 714 The server sends this message after receiving the clients CLIENT- 715 HELLO message. The server returns the SESSION-ID-HIT flag 716 indicating whether or not the received session-identifier is known by the 717 server (i.e. in the server's session-identifier cache). The SESSION-ID- 718 HIT flag will be non-zero if the client sent the server a session-identifier 719 (in the CLIENT-HELLO message with SESSION-ID-LENGTH != 0) 720 and the server found the client's session-identifier in its cache. If the 721 SESSION-ID-HIT flag is non-zero then the CERTIFICATE-TYPE, 722 CERTIFICATE-LENGTH and CIPHER-SPECS-LENGTH fields will 723 be zero. 725 The CERTIFICATE-TYPE value, when non-zero, has one of the values 726 described above (see the information on the CLIENT-CERTIFICATE 727 message). 729 When the SESSION-ID-HIT flag is zero, the server packages up its 730 certificate, its cipher specs and a connection-id to send to the client. Using 731 this information the client can generate a session key and return it to the 732 server with the CLIENT-MASTER-KEY message. 734 When the SESSION-ID-HIT flag is non-zero, both the server and the 735 client compute a new pair of session keys for the current session derived 736 from the MASTER-KEY that was exchanged when the SESSION-ID 737 was created. The SERVER-READ-KEY and SERVER-WRITE-KEY 738 are derived from the original MASTER-KEY keys in the same manner as 739 the CLIENT-READ-KEY and CLIENT-WRITE-KEY: 741 SERVER-READ-KEY = CLIENT-WRITE-KEY 742 SERVER-WRITE-KEY = CLIENT-READ-KEY 744 Note that when keys are being derived and the SESSION-ID-HIT flag is 745 set and the server discovers the client's session-identifier in the servers 746 cache, then the KEY-ARG-DATA is used from the time when the 748 SESSION-ID was established. This is because the client does not send 749 new KEY-ARG-DATA (recall that the KEY-ARG-DATA is sent only in 750 the CLIENT-MASTER-KEY message). 752 The CONNECTION-ID-DATA is a string of randomly generated bytes 753 used by the server and client at various points in the protocol. The 754 CLIENT-FINISHED message contains an encrypted version of the 755 CONNECTION-ID-DATA. The length of the CONNECTION-ID must 756 be between 16 and than 32 bytes, inclusive. 758 The CIPHER-SPECS-DATA define a cipher type and key length (in bits) 759 that the receiving end supports. Each SESSION-CIPHER-SPEC is 3 760 bytes long and looks like this: 762 char CIPHER-KIND-0 763 char CIPHER-KIND-1 764 char CIPHER-KIND-2 766 Where CIPHER-KIND is one of: 768 SSL_CK_RC4_128_WITH_MD5 769 SSL_CK_RC4_128_EXPORT40_WITH_MD5 770 SSL_CK_RC2_128_CBC_WITH_MD5 771 SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5 772 SSL_CK_IDEA_128_CBC_WITH_MD5 773 SSL_CK_DES_64_CBC_WITH_MD5 774 SSL_CK_DES_192_EDE3_CBC_WITH_MD5 776 This list is not exhaustive and may be changed in the future. 778 The SSL_CK_RC4_128_EXPORT40_WITH_MD5 cipher is an RC4 779 cipher where some of the session key is sent in the clear and the rest is sent 780 encrypted (exactly 40 bits of it). MD5 is used as the hash function for 781 production of MAC's and session key's. This cipher type is provided to 782 support "export" versions (i.e. versions of the protocol that can be 783 distributed outside of the United States) of the client or server. 785 An exportable implementation of the SSL Handshake Protocol will have 786 secret key lengths restricted to 40 bits. For non-export implementations 787 key lengths can be more generous (we recommend at least 128 bits). It is 788 permissible for the client and server to have a non-intersecting set of 789 stream ciphers. This, simply put, means they cannot communicate. 791 Version 2 of the SSL Handshake Protocol defines the 792 SSL_CK_RC4_128_WITH_MD5 to have a key length of 128 bits. The 793 SSL_CK_RC4_128_EXPORT40_WITH_MD5 also has a key length of 794 128 bits. However, only 40 of the bits are secret (the other 88 bits are sent 795 in the clear by the client to the server). 797 The SERVER-HELLO message is sent after the server receives the 798 CLIENT-HELLO message, and before the server sends the SERVER- 799 VERIFY message. 800 5.6.2 SERVER-VERIFY (Phase 1; Sent encrypted) 802 char MSG-SERVER-VERIFY 804 char CHALLENGE-DATA[N-1] 806 The server sends this message after a pair of session keys (SERVER- 807 READ-KEY and SERVER-WRITE-KEY) have been agreed upon either 808 by a session-identifier or by explicit specification with the CLIENT- 809 MASTER-KEY message. The message contains an encrypted copy of the 810 CHALLENGE-DATA sent by the client in the CLIENT-HELLO 811 message. 813 "N" is the number of bytes in the message that was sent, so "N-1" is the 814 number of bytes in the CHALLENGE-DATA without the message 815 header byte. 817 This message is used to verify the server as follows. A legitimate server 818 will have the private key that corresponds to the public key contained in 819 the server certificate that was transmitted in the SERVER-HELLO 820 message. Accordingly, the legitimate server will be able to extract and 821 reconstruct the pair of session keys (SERVER-READ-KEY and 822 SERVER-WRITE-KEY). Finally, only a server that has done the 823 extraction and decryption properly can correctly encrypt the 824 CHALLENGE-DATA. This, in essence, "proves" that the server has the 825 private key that goes with the public key in the server's certificate. 827 The CHALLENGE-DATA must be the exact same length as originally 828 sent by the client in the CLIENT-HELLO message. Its value must match 829 exactly the value sent in the clear by the client in the CLIENT-HELLO 830 message. The client must decrypt this message and compare the value 831 received with the value sent, and only if the values are identical is the 832 server to be "trusted". If the lengths do not match or the value doesn't 833 match then the connection is to be closed by the client. 835 This message must be sent by the server to the client after either detecting 836 a session-identifier hit (and replying with a SERVER-HELLO message 837 with SESSION-ID-HIT not equal to zero) or when the server receives the 838 CLIENT-MASTER-KEY message. This message must be sent before 839 any Phase 2 messages or a SERVER-FINISHED message. 841 5.6.3 SERVER-FINISHED (Phase 2; Sent encrypted) 843 char MSG-SERVER-FINISHED 844 char SESSION-ID-DATA[N-1] 846 The server sends this message when it is satisfied with the clients security 847 handshake and is ready to proceed with transmission/reception of the 848 higher level protocols data. The SESSION-ID-DATA is used by the client 849 and the server at this time to add entries to their respective session- 850 identifier caches. The session-identifier caches must contain a copy of the 851 MASTER-KEY sent in the CLIENT-MASTER-KEY message as the 852 master key is used for all subsequent session key generation. 854 "N" is the number of bytes in the message that was sent, so "N-1" is the 855 number of bytes in the SESSION-ID-DATA without the message header 856 byte. 858 This message must be sent after the SERVER-VERIFY message. 860 5.6.4 REQUEST-CERTIFICATE (Phase 2; Sent encrypted) 862 char MSG-REQUEST-CERTIFICATE 863 char AUTHENTICATION-TYPE 864 char CERTIFICATE-CHALLENGE-DATA[N-2] 866 A server may issue this request at any time during the second phase of the 867 connection handshake, asking for the client's certificate. The client 868 responds with a CLIENT-CERTIFICATE message immediately if it has 869 one, or an ERROR message (with error code NO-CERTIFICATE- 870 ERROR) if it doesn't. The CERTIFICATE-CHALLENGE-DATA is a 871 short byte string (whose length is greater than or equal to 16 bytes and less 872 than or equal to 32 bytes) that the client will use to respond to this 873 message. 875 The AUTHENTICATION-TYPE value is used to choose a particular 876 means of authenticating the client. The following types are defined: 878 SSL_AT_MD5_WITH_RSA_ENCRYPTION 880 The SSL_AT_MD5_WITH_RSA_ENCRYPTION type requires that the 881 client construct an MD5 message digest using information as described 882 above in the section on the CLIENT-CERTIFICATE message. Once the 883 digest is created, the client encrypts it using its private key (formatted 884 according to the digital signature standard defined in PKCS#1). The server 885 authenticates the client when it receives the CLIENT-CERTIFICATE 886 message. 888 This message may be sent after a SERVER-VERIFY message and before 889 a SERVER-FINISHED message. 891 5.7 Client/Server Protocol Messages 893 These messages are generated by both the client and the server. 895 5.7.1 ERROR (Sent clear or encrypted) 897 char MSG-ERROR 898 char ERROR-CODE-MSB 899 char ERROR-CODE-LSB 901 This message is sent when an error is detected. After the message is sent, 902 the sending party shuts the connection down. The receiving party records 903 the error and then shuts its connection down. 905 This message is sent in the clear if an error occurs during session key 906 negotiation. After a session key has been agreed upon, errors are sent 907 encrypted like all other messages. 909 Appendix A: ASN.1 Syntax For Certificates 911 Certificates are used by SSL to authenticate servers and clients. SSL 912 Certificates are based largely on the X.509 [3] certificates. An X.509 913 certificate contains the following information (in ASN.1 [1] notation): 915 X.509-Certificate ::= SEQUENCE { 916 certificateInfo CertificateInfo, 917 signatureAlgorithm AlgorithmIdentifier, 918 signature BIT STRING 919 } 921 CertificateInfo ::= SEQUENCE { 922 version [0] Version DEFAULT v1988, 923 serialNumber CertificateSerialNumber, 924 signature AlgorithmIdentifier, 925 issuer Name, 926 validity Validity, 927 subject Name, 928 subjectPublicKeyInfo SubjectPublicKeyInfo 929 } 931 Version ::= INTEGER { v1988(0) } 933 CertificateSerialNumber ::= INTEGER 935 Validity ::= SEQUENCE { 936 notBefore UTCTime, 937 notAfter UTCTime 938 } 940 SubjectPublicKeyInfo ::= SEQUENCE { 941 algorithm AlgorithmIdentifier, 942 subjectPublicKey BIT STRING 943 } 945 AlgorithmIdentifier ::= SEQUENCE { 946 algorithm OBJECT IDENTIFIER, 947 parameters ANY DEFINED BY ALGORITHM OPTIONAL 948 } 950 For SSL's purposes we restrict the values of some of the X.509 fields: 952 The X.509-Certificate::signatureAlgorithm and 953 CertificateInfo::signature fields must be identical in value. 955 The issuer name must resolve to a name that is deemed acceptable by 956 the application using SSL. How the application using SSL does this is 957 outside the scope of this memo. 959 Certificates are validated using a few straightforward steps. First, the 960 signature on the certificate is checked and if invalid, the certificate is 961 invalid (either a transmission error or an attempted forgery occurred). 962 Next, the CertificateInfo::issuer field is verified to be an issuer that the 963 application trusts (using an unspecified mechanism). The 964 CertificateInfo::validity field is checked against the current date and 965 verified. 967 Finally, the CertificateInfo::subject field is checked. This check is 968 optional and depends on the level of trust required by the application using 969 SSL. 971 Appendix B: Attribute Types and Object Identifiers 973 SSL uses a subset of the X.520 selected attribute types as well as a 974 few specific object identifiers. Future revisions of the SSL protocol 975 may include support for more attribute types and more object 976 identifiers. 978 B.1 Selected attribute types 980 commonName { attributeType 3 } 981 The common name contained in the distinguished name contained 982 within a certificate issuer or certificate subject. 984 countryName { attributeType 6 } 985 The country name contained in the distinguished name contained 986 within a certificate issuer or certificate subject. 988 localityName { attributeType 7 } 989 The locality name contained in the distinguished name contained 990 within a certificate issuer or certificate subject. 992 stateOrProvinceName { attributeType 8 } 993 The state or province name contained in the distinguished name 994 contained within a certificate issuer or certificate subject. 996 organizationName { attributeType 10 } 997 The organization name contained in the distinguished name contained 998 within a certificate issuer or certificate subject. 1000 organizationalUnitName { attributeType 11 } 1001 The organizational unit name contained in the distinguished name 1002 contained within a certificate issuer or certificate subject. 1004 B.2 Object identifiers 1006 md2withRSAEncryption { ... pkcs(1) 1 2 } 1007 The object identifier for digital signatures that use both MD2 and RSA 1008 encryption. Used by SSL for certificate signature verification. 1010 md5withRSAEncryption { ... pkcs(1) 1 4 } 1011 The object identifier for digital signatures that use both MD5 and RSA 1012 encryption. Used by SSL for certificate signature verification. 1014 rc4 { ... rsadsi(113549) 3 4 } 1015 The RC4 symmetric stream cipher algorithm used by SSL for bulk 1016 encryption. 1018 Appendix C: Protocol Constant Values 1020 This section describes various protocol constants. A special value needs 1021 mentioning - the IANA reserved port number for "https" (HTTP using 1022 SSL). IANA has reserved port number 443 (decimal) for "https". IANA 1023 has also reserved port number 465 for "ssmtp" and port number 563 for 1024 "snntp". 1026 C.1 Protocol Version Codes 1028 #define SSL_CLIENT_VERSION 0x0002 1029 #define SSL_SERVER_VERSION 0x0002 1031 C.2 Protocol Message Codes 1033 The following values define the message codes that are used by version 1034 2 of the SSL Handshake Protocol. 1036 #define SSL_MT_ERROR 0 1037 #define SSL_MT_CLIENT_HELLO 1 1038 #define SSL_MT_CLIENT_MASTER_KEY 2 1039 #define SSL_MT_CLIENT_FINISHED 3 1040 #define SSL_MT_SERVER_HELLO 4 1041 #define SSL_MT_SERVER_VERIFY 5 1042 #define SSL_MT_SERVER_FINISHED 6 1043 #define SSL_MT_REQUEST_CERTIFICATE 7 1044 #define SSL_MT_CLIENT_CERTIFICATE 8 1046 C.3 Error Message Codes 1048 The following values define the error codes used by the ERROR message. 1050 #define SSL_PE_NO_CIPHER 0x0001 1051 #define SSL_PE_NO_CERTIFICATE 0x0002 1052 #define SSL_PE_BAD_CERTIFICATE 0x0004 1053 #define SSL_PE_UNSUPPORTED_CERTIFICATE_TYPE 0x0006 1055 C.4 Cipher Kind Values 1057 The following values define the CIPHER-KIND codes used in the 1058 CLIENT-HELLO and SERVER-HELLO messages. 1060 #define SSL_CK_RC4_128_WITH_MD5 1061 0x01,0x00,0x80 1062 #define SSL_CK_RC4_128_EXPORT40_WITH_MD5 1063 0x02,0x00,0x80 1064 #define SSL_CK_RC2_128_CBC_WITH_MD5 1065 0x03,0x00,0x80 1066 #define SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5 1067 0x04,0x00,0x80 1068 #define SSL_CK_IDEA_128_CBC_WITH_MD5 1069 0x05,0x00,0x80 1070 #define SSL_CK_DES_64_CBC_WITH_MD5 1071 0x06,0x00,0x40 1072 #define SSL_CK_DES_192_EDE3_CBC_WITH_MD5 1073 0x07,0x00,0xC0 1075 C.5 Certificate Type Codes 1077 The following values define the certificate type codes used in the 1078 SERVER-HELLO and CLIENT-CERTIFICATE messages. 1080 #define SSL_CT_X509_CERTIFICATE 0x01 1082 C.6 Authentication Type Codes 1084 The following values define the authentication type codes used in the 1085 REQUEST-CERTIFICATE message. 1087 #define SSL_AT_MD5_WITH_RSA_ENCRYPTION 0x01 1089 C.7 Upper/Lower Bounds 1091 The following values define upper/lower bounds for various protocol 1092 parameters. 1094 #define SSL_MAX_MASTER_KEY_LENGTH_IN_BITS 256 1095 #define SSL_MAX_SESSION_ID_LENGTH_IN_BYTES 16 1096 #define SSL_MIN_RSA_MODULUS_LENGTH_IN_BYTES 64 1097 #define SSL_MAX_RECORD_LENGTH_2_BYTE_HEADER 32767 1098 #define SSL_MAX_RECORD_LENGTH_3_BYTE_HEADER 16383 1100 C.8 Recommendations 1102 Because protocols have to be implemented to be of value, we recommend 1103 the following values for various operational parameters. This is only a 1104 recommendation, and not a strict requirement for conformance to the 1105 protocol. 1107 Session-identifier Cache Timeout 1109 Session-identifiers are kept in SSL clients and SSL servers. Session- 1110 identifiers should have a lifetime that serves their purpose (namely, 1111 reducing the number of expensive public key operations for a single 1112 client/server pairing). Consequently, we recommend a maximum session- 1113 identifier cache timeout value of 100 seconds. Given a server that can 1114 perform N private key operations per second, this reduces the server load 1115 for a particular client by a factor of 100. 1117 Appendix D: Attacks 1119 In this section we attempt to describe various attacks that might be used 1120 against the SSL protocol. This list is not guaranteed to be exhaustive. SSL 1121 was defined to thwart these attacks. 1123 D.1 Cracking Ciphers 1125 SSL depends on several cryptographic technologies. RSA Public Key 1126 encryption [5] is used for the exchange of the session key and client/server 1127 authentication. Various cryptographic algorithms are used for the session 1128 cipher. If successful cryptographic attacks are made against these 1129 technologies then SSL is no longer secure. 1131 Attacks against a specific communications session can be made by 1132 recording the session, and then spending some large number of compute 1133 cycles to crack either the session key or the RSA public key until the 1134 communication can be seen in the clear. This approach is easier than 1135 cracking the cryptographic technologies for all possible messages. Note 1136 that SSL tries to make the cost of such of an attack greater than the 1138 benefits gained from a successful attack, thus making it a waste of 1139 money/time to perform such an attack. 1141 There have been many books [9] and papers [10] written on cryptography. 1142 This document does not attempt to reference them all. 1144 D.2 Clear Text Attack 1146 A clear text attack is done when the attacker has an idea of what kind of 1147 message is being sent using encryption. The attacker can generate a data 1148 base whose keys are the encrypted value of the known text (or clear text), 1149 and whose values are the session cipher key (we call this a "dictionary"). 1150 Once this data base is constructed, a simple lookup function identifies the 1151 session key that goes with a particular encrypted value. Once the session 1152 key is known, the entire message stream can be decrypted. Custom 1153 hardware can be used to make this cost effective and very fast. 1155 Because of the very nature of SSL clear text attacks are possible. For 1156 example, the most common byte string sent by an HTTP client application 1157 to an HTTP server is "GET". SSL attempts to address this attack by using 1158 large session cipher keys. First, the client generates a key which is larger 1159 than allowed by export, and sends some of it in the clear to the server (this 1160 is allowed by United States government export rules). The clear portion of 1161 the key concatenated with the secret portion make a key which is very 1162 large (for RC4, exactly 128 bits). 1164 The way that this "defeats" a clear text attack is by making the amount of 1165 custom hardware needed prohibitively large. Every bit added to the length 1166 of the session cipher key increases the dictionary size by a factor of 2. By 1167 using a 128 bit session cipher key length the size of the dictionary required 1168 is beyond the ability of anyone to fabricate (it would require more atoms to 1169 construct than exist in the entire universe). Even if a smaller dictionary is 1170 to be used, it must first be generated using the clear key bits. This is a time 1171 consumptive process and also eliminates many possible custom hardware 1172 architectures (e.g. static prom arrays). 1174 The second way that SSL attacks this problem is by using large key 1175 lengths when permissible (e.g. in the non-export version). Large key sizes 1176 require larger dictionaries (just one more bit of key size doubles the size of 1177 the dictionary). SSL attempts to use keys that are 128 bits in length. 1179 Note that the consequence of the SSL defense is that a brute force attack 1180 becomes the cheapest way to attack the key. Brute force attacks have well 1181 known space/time tradeoffs and so it becomes possible to define a cost of 1182 the attack. For the 128 bit secret key, the known cost is essentially infinite. 1183 For the 40 bit secret key, the cost is much smaller, but still outside the 1184 range of the "random hacker". 1186 D.3 Replay 1188 The replay attack is simple. A bad-guy records a communication session 1189 between a client and server. Later, it reconnects to the server, and plays 1190 back the previously recorded client messages. SSL defeats this attack 1191 using a "nonce" (the connection-id) which is "unique" to the connection. In 1192 theory the bad-guy cannot predict the nonce in advance as it is based on a 1194 set of random events outside the bad-guys control, and therefore the bad- 1195 guy cannot respond properly to server requests. 1197 A bad-guy with large resources can record many sessions between a client 1198 and a server, and attempt to choose the right session based on the nonce 1199 the server sends initially in its SERVER-HELLO message. However, SSL 1200 nonces are at least 128 bits long, so a bad-guy would need to record 1201 approximately 2^64 nonces to even have a 50% chance of choosing the 1202 right session. This number is sufficiently large that one cannot 1203 economically construct a device to record 2^64 messages, and therefore 1204 the odds are overwhelmingly against the replay attack ever being 1205 successful. 1207 D.4 The Man In The Middle 1209 The man in the middle attack works by having three people in a 1210 communications session: the client, the server, and the bad guy. The bad 1211 guy sits between the client and the server on the network and intercepts 1212 traffic that the client sends to the server, and traffic that the server 1213 sends to 1214 the client. 1216 The man in the middle operates by pretending to be the real server to the 1217 client. With SSL this attack is impossible because of the usage of server 1218 certificates. During the security connection handshake the server is 1219 required to provide a certificate that is signed by a certificate authority. 1220 Contained in the certificate is the server's public key as well as its name 1221 and the name of the certificate issuer. The client verifies the certificate by 1222 first checking the signature and then verifying that the name of the issuer 1223 is somebody that the client trusts. 1225 In addition, the server must encrypt something with the private key that 1226 goes with the public key mentioned in the certificate. This in essence is a 1227 single pass "challenge response" mechanism. Only a server that has both 1228 the certificate and the private key can respond properly to the challenge. 1230 If the man in the middle provides a phony certificate, then the signature 1231 check will fail. If the certificate provided by the bad guy is legitimate, but 1232 for the bad guy instead of for the real server, then the signature will pass 1233 but the name check will fail (note that the man in the middle cannot forge 1234 certificates without discovering a certificate authority's private key). 1236 Finally, if the bad guy provides the real server's certificate then the 1237 signature check will pass and the name check will pass. However, because 1238 the bad guy does not have the real server's private key, the bad guy cannot 1239 properly encode the response to the challenge code, and this check will 1240 fail. 1242 In the unlikely case that a bad guy happens to guess the response code to 1243 the challenge, the bad guy still cannot decrypt the session key and 1244 therefore cannot examine the encrypted data. 1246 Appendix E: Terms 1248 Application Protocol 1249 An application protocol is a protocol that normally layers directly on 1250 top of TCP/IP. For example: HTTP, TELNET, FTP, and SMTP. 1252 Authentication 1253 Authentication is the ability of one entity to determine the identity of 1254 another entity. Identity is defined by this document to mean the 1255 binding between a public key and a name and the implicit ownership 1256 of the corresponding private key. 1258 Bulk Cipher 1259 This term is used to describe a cryptographic technique with certain 1260 performance properties. Bulk ciphers are used when large quantities of 1261 data are to be encrypted/decrypted in a timely manner. Examples 1262 include RC2, RC4, and IDEA. 1264 Client 1265 In this document client refers to the application entity that is initiates a 1266 connection to a server. 1268 CLIENT-READ-KEY 1269 The session key that the client uses to initialize the client read cipher. 1270 This key has the same value as the SERVER-WRITE-KEY. 1272 CLIENT-WRITE-KEY 1273 The session key that the client uses to initialize the client write cipher. 1274 This key has the same value as the SERVER-READ-KEY. 1276 MASTER-KEY 1277 The master key that the client and server use for all session key 1278 generation. The CLIENT-READ-KEY, CLIENT-WRITE-KEY, 1279 SERVER-READ-KEY and SERVER-WRITE-KEY are generated 1280 from the MASTER-KEY. 1282 MD2 1283 MD2 [8] is a hashing function that converts an arbitrarily long data 1284 stream into a digest of fixed size. This function predates MD5 [7] 1285 which is viewed as a more robust hash function [9]. 1287 MD5 1288 MD5 [7] is a hashing function that converts an arbitrarily long data 1289 stream into a digest of fixed size. The function has certain properties 1290 that make it useful for security, the most important of which is it's 1291 inability to be reversed. 1293 Nonce 1294 A randomly generated value used to defeat "playback" attacks. One 1295 party randomly generates a nonce and sends it to the other party. The 1296 receiver encrypts it using the agreed upon secret key and returns it to 1297 the sender. Because the nonce was randomly generated by the sender 1298 this defeats playback attacks because the replayer can't know in 1299 advance the nonce the sender will generate. The receiver denies 1300 connections that do not have the correctly encrypted nonce. 1302 Non-repudiable Information Exchange 1303 When two entities exchange information it is sometimes valuable to 1304 have a record of the communication that is non-repudiable. Neither 1305 party can then deny that the information exchange occurred. Version 2 1306 of the SSL protocol does not support Non-repudiable information 1307 exchange. 1309 Public Key Encryption 1310 Public key encryption is a technique that leverages asymmetric ciphers. 1311 A public key system consists of two keys: a public key and a private 1312 key. Messages encrypted with the public key can only be decrypted 1313 with the associated private key. Conversely, messages encrypted with 1314 the private key can only be decrypted with the public key. Public key 1315 encryption tends to be extremely compute intensive and so is not 1316 suitable as a bulk cipher. 1318 Privacy 1319 Privacy is the ability of two entities to communicate without fear of 1320 eavesdropping. Privacy is often implemented by encrypting the 1321 communications stream between the two entities. 1323 RC2, RC4 1324 Proprietary bulk ciphers invented by RSA (There is no good reference 1325 to these as they are unpublished works; however, see [9]). RC2 is 1326 block cipher and RC4 is a stream cipher. 1328 Server 1329 The server is the application entity that responds to requests for 1330 connections from clients. The server is passive, waiting for requests 1331 from clients. 1333 Session cipher 1334 A session cipher is a "bulk" cipher that is capable of encrypting or 1335 decrypting arbitrarily large amounts of data. Session ciphers are used 1336 primarily for performance reasons. The session ciphers used by this 1337 protocol are symmetric. Symmetric ciphers have the property of using 1338 a single key for encryption and decryption. 1340 Session identifier 1341 A session identifier is a random value generated by a client that 1342 identifies itself to a particular server. The session identifier can be 1343 thought of as a handle that both parties use to access a recorded secret 1344 key (in our case a session key). If both parties remember the session 1345 identifier then the implication is that the secret key is already known 1346 and need not be negotiated. 1348 Session key 1349 The key to the session cipher. In SSL there are four keys that are called 1350 session keys: CLIENT-READ-KEY, CLIENT-WRITE-KEY, 1351 SERVER-READ-KEY, and SERVER-WRITE-KEY. 1353 SERVER-READ-KEY 1354 The session key that the server uses to initialize the server read cipher. 1355 This key has the same value as the CLIENT-WRITE-KEY. 1357 SERVER-WRITE-KEY 1358 The session key that the server uses to initialize the server write cipher. 1359 This key has the same value as the CLIENT-READ-KEY. 1361 Symmetric Cipher 1362 A symmetric cipher has the property that the same key can be used for 1363 decryption and encryption. An asymmetric cipher does not have this 1364 behavior. Some examples of symmetric ciphers: IDEA, RC2, RC4. 1366 References 1368 [1] CCITT. Recommendation X.208: "Specification of Abstract Syntax 1369 Notation One (ASN.1). 1988. 1371 [2] CCITT. Recommendation X.209: "Specification of Basic Encoding 1372 Rules for Abstract Syntax Notation One (ASN.1). 1988. 1374 [3] CCITT. Recommendation X.509: "The Directory - Authentication 1375 Framework". 1988. 1377 [4] CCITT. Recommendation X.520: "The Directory - Selected Attribute 1378 Types". 1988. 1380 [5] RSA Laboratories. PKCS #1: RSA Encryption Standard, Version 1.5, 1381 November 1993. 1383 [6] RSA Laboratories. PKCS #6: Extended-Certificate Syntax Standard, 1384 Version 1.5, November 1993. 1386 [7] R. Rivest. RFC 1321: The MD5 Message Digest Algorithm. April 1387 1992. 1389 [8] R. Rivest. RFC 1319: The MD2 Message Digest Algorithm. April 1390 1992. 1392 [9] B. Schneier. Applied Cryptography: Protocols, Algorithms, and Source 1393 Code in C, Published by John Wiley & Sons, Inc. 1994. 1395 [10] M. Abadi and R. Needham. Prudent engineering practice for 1396 cryptographic protocols. 1994. 1398 Patent Statement 1400 This version of the SSL protocol relies on the use of patented public key 1401 encryption technology for authentication and encryption. The Internet 1402 Standards Process as defined in RFC 1310 requires a written statement 1403 from the Patent holder that a license will be made available to applicants 1404 under reasonable terms and conditions prior to approving a specification as 1405 a Proposed, Draft or Internet Standard. 1407 The Massachusetts Institute of Technology and the Board of Trustees of 1408 the Leland Stanford Junior University have granted Public Key Partners 1409 (PKP) exclusive sub-licensing rights to the following patents issued in the 1411 United States, and all of their corresponding foreign patents: 1413 Cryptographic Apparatus and Method ("Diffie-Hellman") 1414 No. 4,200,770 1416 Public Key Cryptographic Apparatus and Method ("Hellman-Merkle") 1417 No. 4,218,582 1419 Cryptographic Communications System and Method ("RSA") 1420 No. 4,405,829 1422 Exponential Cryptographic Apparatus and Method ("Hellman-Pohlig") 1423 No. 4,424,414 1425 These patents are stated by PKP to cover all known methods of practicing 1426 the art of Public Key encryption, including the variations collectively 1427 known as ElGamal. 1429 Public Key Partners has provided written assurance to the Internet Society 1430 that parties will be able to obtain, under reasonable, nondiscriminatory 1431 terms, the right to use the technology covered by these patents. This 1432 assurance is documented in RFC 1170 titled "Public Key Standards and 1433 Licenses". A copy of the written assurance dated April 20, 1990, may be 1434 obtained from the Internet Assigned Number Authority (IANA). 1436 The Internet Society, Internet Architecture Board, Internet Engineering 1437 Steering Group and the Corporation for National Research Initiatives take 1438 no position on the validity or scope of the patents and patent applications, 1439 nor on the appropriateness of the terms of the assurance. The Internet 1440 Society and other groups mentioned above have not made any 1441 determination as to any other intellectual property rights which may apply 1442 to the practice of this standard. Any further consideration of these matters 1443 is the user's own responsibility. 1445 Security Considerations 1447 This entire document is about security. 1449 Author's Address 1451 Kipp E.B. Hickman 1452 Netscape Communications Corp. 1453 501 East Middlefield Rd. 1454 Mountain View, CA 94043 1455 kipp@netscape.com