diff options
Diffstat (limited to 'doc/protocol/draft-benaloh-pct-01.txt')
| -rw-r--r-- | doc/protocol/draft-benaloh-pct-01.txt | 2649 |
1 files changed, 0 insertions, 2649 deletions
diff --git a/doc/protocol/draft-benaloh-pct-01.txt b/doc/protocol/draft-benaloh-pct-01.txt deleted file mode 100644 index f9e61ba096..0000000000 --- a/doc/protocol/draft-benaloh-pct-01.txt +++ /dev/null @@ -1,2649 +0,0 @@ - -Internet Draft Daniel Simon - Microsoft Corp. - April 1996 - - The Private Communication Technology Protocol - <draft-benaloh-pct-01.txt> - -1. Status of this Memo - -This document is an Internet-Draft. Internet-Drafts are working -documents of the Internet Engineering Task Force (IETF), its areas, -and its working groups. Note that other groups may also distribute -working documents as Internet-Drafts. - -Internet-Drafts are draft documents valid for a maximum of six months -and may be updated, replaced, or obsoleted by other documents at any -time. It is inappropriate to use Internet-Drafts as reference -material or to cite them other than as "work in progress". - -To learn the current status of any Internet-Draft, please check the -"1id-abstracts.txt" listing contained in the Internet-Drafts Shadow -Directories on ds.internic.net (US East Coast), nic.nordu.net -(Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). - -This Internet-Draft expires 10 October 1996. - - -2. Abstract - -This document specifies Version 2 of the Private Communication -Technology (PCT) protocol, a security protocol that provides privacy -over the Internet. The protocol is intended to prevent eavesdropping -on connection-based communications in client/server applications, -with at least one of the two always being authenticated, and each -having the option of requiring authentication of the other. PCT is -somewhat similar to SSL ([1]); however, PCT version 1 corrects -or improves on several weaknesses of SSL, and version 2 also adds a -number of new features. PCT version 2 is fully compatible with PCT -version 1. - - -3. Introduction - -The Private Communication Technology (PCT) Protocol is designed to -provide privacy between two communicating applications (a client and a -server), and to authenticate at least one of the two (typically the -server) to the other. The PCT Protocol is application -protocol-independent. A "higher level" application protocol (e.g. -HTTP, FTP, TELNET, etc.) can layer on top of the PCT Protocol -transparently. - -In the PCT protocol, all data is transmitted in the form of -variable-length records, each of which has a record header. These -records are used to transmit both PCT protocol messages (including -handshake, error, and key management messages) and application data -messages. Exchanges of records between a client and server are -grouped into "connections", which are in turn grouped into "sessions". -Every PCT connection belongs to some particular session. - -Every PCT protocol connection begins with a handshake phase, during -which a sequence of handshake messages (comprising the PCT Handshake -Protocol) are exchanged, which negotiate a (symmetric) session key -for the connection, as well as performing the requested -authentications based on certified asymmetric public (signature or -key exchange) keys (or on previously shared private "password" keys). -Once transmission of application protocol data messages begins in a -connection, all data (including error and key management messages) is -encrypted using encryption keys derived from a "master key" exchanged -during some handshake phase of the connection's session, as well as -from the handshake messages that began the connection. In addition -to encryption and authentication, the PCT protocol verifies the -integrity of messages using a hash function-based message -authentication code (MAC). - -PCT assumes a reliable transport protocol (e.g. TCP) for PCT record -transmission and reception during the handshake phase (and -afterwards as well in version 1); however, use of datagram records -in version 2 makes it possible for individual records to be sent -independently (as "datagrams"), with neither order nor eventual -delivery guaranteed. - -It should be noted that the PCT protocol does not specify any details -about verification of identities or certificates with respect to -account administrators, certification authorities, revocation lists, -and so on. Rather, it is assumed that protocol implementations have -access to a "black box" which is capable of ruling on the validity of -received identities and certificates in a manner satisfactory to the -implementation's user. Such a ruling may, for instance, involve -remote consultation with a trusted service, or even with the actual -user through a text or graphic interface. - -The PCT protocol's compatibility with, and differences from, SSL -([1]) are outlined in the specification of PCT version 1 ([2]). -PCT version 2 is fully compatible with PCT version 1, in that an -implementation of version 1 is a valid (though less feature-rich) -implementation of version 2. If either the client or server (or -both) identifies itself during the handshake phase as using PCT -version 1, then the session conforms to the PCT version 1 -specification, and features introduced in version 2 are not available. -PCT version 1 compatibility details are given in section 8. - -PCT version 2 is different from PCT version 1 in the following -respects: - -- PCT version 2 has a revised record format which allows handshake - records, error records and data records, as well as "key management" - and "datagram" records (two new record types) to be explicitly - recognized and distinguished from each other based on header - information. Record headers can also indicate continuations of - previous records, allowing protocol messages of any type to span - multiple records, just as user data already does in PCT version 1. - Finally, encapsulating user data in a new "data message" format - allows the invocation (using assigned data message types) of - intermediate processing, such as compression/decompression, - -- PCT version 2 "datagram" records are independently decryptable, - allowing encrypted data to be sent securely across unreliable - transports, where neither delivery nor correct order are - guaranteed. - -- PCT version 2 "key management" records allow encryption and/or - message authentication keys to be temporarily changed within a - session, to support the transport of pre-encrypted data. - -- PCT version 2 adds a "closing connection" key management message to - ensure that connections aren't prematurely closed by someone - unauthorized to do so. - -- PCT version 2 message authentication is altered to include record - headers. - -- The handshake phase of PCT version 2 allows a wider, more symmetrical - variety of authentication options: either client or server or both - may be authenticated, each by means of either a key exchange or - signature public key and certificate. - -- PCT version 2 allows a new "private" authentication type, in which - authentication is based on a previously shared identity-associated - private key, rather than a certified public key. - - -4. PCT Record Protocol Specification - -4.1 Notation - -The following notation is used in this specification to represent -data field formats in various protocol messages: - -char MSG_EXAMPLE -char FIELD1 -char FIELD2 -char THING_LENGTH[2] -char ANOTHER_THING_LENGTH[4] -char THING_DATA[([0] << 8)|[1]] -char ANOTHER_THING_DATA[([0]<<24)|([1]<<16)|([2]<<8)|[3]] -... - -The order is presented top to bottom, with the topmost field being -transmitted first. The "FIELD1" and "FIELD2" fields are each one -byte long; the "THING_LENGTH" and "ANOTHER_THING_LENGTH" fields have -lengths of two and four bytes, respectively, as indicated by the -numbers in square brackets following the field labels. Their bytes -are indexed by their offset from the beginning of the field, starting -with THING_LENGTH[0] and ANOTHER_THING_LENGTH[0], which are the -first bytes transmitted in their respective fields. - -In the "THING_DATA" and "ANOTHER_THING_DATA" entries, the values in -square brackets indicate byte offset indices in THING_LENGTH and -ANOTHER_THING_LENGTH, respectively. As presented above, the notation -refers to combining the bytes of the LENGTH field in order to form an -unsigned integer, with the bytes arranged in decreasing order of -significance. This integer defines the number of bytes of data in -the corresponding DATA field. For example, if THING_LENGTH[0] were -one and THING_LENGTH[1] were four then the THING_DATA array would be -exactly 260 bytes long. And if the values of the four bytes of -ANOTHER_THING_LENGTH were zero, one, two and four, respectively, then -ANOTHER_THING_DATA would be exactly 66,052 bytes long. This -shorthand form is used throughout the specification; occasionally, a -"THING_DATA" field is referred to as "THING", with the word "DATA" -omitted. - -Individual bits within a data field are denoted as follows: - -LEAST_SIGNIFICANT_BIT := 0x0001 -NEXT_LEAST_SIG_BIT := 0x0002 -THIRD_LEAST_SIG_BIT := 0x0004 -... - -These bit identifiers correspond to the least, second-least and -third-least significant bits (in that order) in a two-byte data -field. The associated hexadecimal values consist of all zero bits -except for the identified bit. - -Computations involving a hash function (sometimes iterated) are -denoted as follows: - -COMPUTATION_RESULT_i = Hash( "ASCII string hash input 1"^i, -HASH_INPUT_2, HASH_INPUT_3^i, Hash( "ASCII string hash input 4", -HASH_INPUT_5, i ) ) - -The values in quotation marks are treated as (sequences of) ASCII -characters; "x"^i (or VARIABLE^i) denotes i copies of the string -"x" (or variable VARIABLE, respectively) concatenated together. The -parameters are input into the hash function in the order presented; -the variable i, wherever it appears as an input value, is input as a -single-byte unsigned integer. If any input has a length which is not -an integral number of bytes, then (fewer than eight) zero bits are -appended to its last byte to produce an input which is an integral -number of bytes. The value of COMPUTATION_RESULT is obtained by -concatenating the COMPUTATION_RESULT_i values in order, for values of -i in a specified range. (If no subscript i is present in the -specified formula, then the implied range includes only the value 1.) -If the resulting value requires truncation, then the truncation is -performed by removing bits from the end to obtain a string of the -required length. - -In the case of elements of specifically named records or messages, -the names of record or message elements have prefixes that identify -the messages in which they appear. These prefixes are sometimes -omitted in the text when the containing messages are obvious, or -when the same elements have more than one possible prefix. - - -4.2 PCT Record Format - -4.2.1 Record header format - -A PCT record consists of a four-byte header followed by a -variable-length body. The maximum length of the body is 32763 -bytes. - -The PCT record header formats differ in versions 1 and 2. The -version 2 record header will be described in this section; its -compatibility with the version 1 header (which is described fully -in [2]) is explained in section 8. - -The PCT version 2 record header has the following structure: - -char RH_RECORD_LENGTH[2] -char RH_RECORD_TYPE[2] - -RECORD_LENGTH is an unsigned integer representing the length of the -(cleartext) data following the length field in the record header -(including the RH_RECORD_TYPE field and the subsequent record body). -The first (most significant) bit of the first (most significant) -byte of this field is set to one, for backward compatibility reasons -(see section 9); this bit must be reset to zero to obtain the -correct unsigned integer value. Note that if encryption expands the -length of the data, the length of the (fully or partially encrypted) -record body plus RH_RECORD_TYPE field will not match the value in -RECORD_LENGTH; the effect of each cipher on data length is described -in section 6.1.5. - -RECORD_TYPE is a two-byte field indicating the type of contents in the -record, and in particular, how the record should be processed. PCT -version 2 defines a number of record type values for specific record -types; other record types are used to identify PCT version 1 (or -SSL version 2 or 3) connections, for appropriate processing. These -are RT_VERSION_1_CH, RT_VERSION_1_SH, RT_SSL_VERSION_2_CH, -RT_SSL_VERSION_2_SH and RT_SSL_VERSION_3, respectively. (Note that -type RT_SSL_VERSION_3 is defined only on the first, or most -significant, byte; the second, or least significant byte can have -any value.) The normal PCT version 2 record types are RT_HANDSHAKE, -RT_DATAGRAM, RT_KEY_MGMT, RT_ERROR, and RT_USER_DATA; their -associated record data formats are described in section 4.3. All -other defined record types are reserved, and must never be used. -One of them, RT_CD_RESERVED, is also explicitly defined to preclude -use in future versions. - - -4.3 PCT Record Body Formats - -4.3.1 Handshake Record Body Format - -PCT version 2 Handshake records (those with RECORD_TYPE -RT_HANDSHAKE) have a very simple body format: - -char HS_MSG_TYPE[2] -char HS_RECORD_FLAGS[2] -char HS_HANDSHAKE_DATA[RH_RECORD_LENGTH - 6] - -The possible HS_MSG_TYPE values are HS_CLIENT_HELLO, -HS_SERVER_HELLO, HS_CLIENT_MASTER_KEY, HS_SERVER_VERIFY, and -HS_CLIENT_VERIFY. HS_RECORD_FLAGS is a two-byte field containing -informational flags about the handshake record. The only two flags -defined in PCT version 2 are the last (least significant) two bits -of HS_RECORD_FLAGS: - -HS_FLAG_TO_BE_CONTD := 0x0001 -HS_FLAG_CONTINUATION := 0x0002 - -The last (least significant) bit, HS_FLAG_TO_BE_CONTD, indicates -when set that the next record received of the same type is to be -considered a continuation of the current one. The -second-least-significant bit, HS_FLAG_CONTINUATION, indicates when -set that the record is to be considered a continuation of the -previous record received of the same type. (For PCT version 1 -compatibility reasons, a CLIENT_HELLO message must not be continued -over more than one handshake record.) The remaining flag bits are -reserved, and must be set to zero. - -The HS_HANDSHAKE_DATA field contains data from a PCT handshake -message; the structure of these messages is described in section -5.2. Note that a single handshake message may stretch across more -than one handshake record; in that case the appropriate flags are set -in the record header. (A restriction on how a handshake message is -fragmented among records is given in section 5.2.) - -4.3.2 Datagram Records - -A datagram record is an independently decryptable data record; its -enclosed data message can be decrypted, and its MAC checked, -regardless of whether previous records were delivered in order (or -at all). Datagrams can hence be used if the underlying transport -does not guarantee in-order delivery of records; for example, it -makes possible the transmission of "out-of-band" data for rapid -delivery in a TCP connection. - -The format of PCT version 2 datagram records is as follows: - -char DG_ENCRYPTED_KEY_LENGTH[2] -char DG_ENCRYPTED_KEY_DATA[([0] << 8)|[1]] -char DG_ENCRYPTED_DATA[ENCRYPTED_LENGTH] -char DG_MAC_DATA[MAC_LENGTH] - -The DG_ENCRYPTED_KEY_DATA field contains the key information necessary -to perform decryption and MAC verification of the datagram record; its -contents are described in section 6.1.3. The DG_ENCRYPTED_DATA field -contains an encryption of ACTUAL_DATA (consisting of the ACTUAL_LENGTH -bytes of the datagram's enclosed data message). The DG_MAC_DATA field -contains the "Message Authentication Code" (MAC); its contents are -described in section 7.3. Note that ACTUAL_LENGTH can be calculated -directly as RECORD_LENGTH - ENCRYPTED_KEY_LENGTH - MAC_LENGTH - 4. The -length of the encrypted datagram record body plus RH_RECORD_TYPE field -may be greater than RECORD_LENGTH, as a result of expansion during -encryption; see section 6.1.5. - - -4.3.3 Other Record Types - -The bodies of PCT version 2 key management, error and user data -records (those with RECORD_TYPE RT_KEY_MGMT, RT_ERROR and -RT_USER_DATA, respectively) contain encrypted data, in the following -data format: - -char DT_ENCRYPTED_DATA[ENCRYPTED_LENGTH] -char DT_MAC_DATA[MAC_LENGTH] - -The ENCRYPTED_DATA field contains an encryption of ACTUAL_DATA -(consisting of the ACTUAL_LENGTH bytes of the enclosed data message). -The MAC_DATA field contains the "Message Authentication Code" (MAC); -its contents are described in section 7.3. ACTUAL_LENGTH can be -calculated directly as RECORD_LENGTH - MAC_LENGTH - 2. - - -4.4 Key Management Messages - -Key management messages have the following format: - -char KM_KEY_MGMT_TYPE[2] -char KM_NEW_HASH_TYPE[2] -char KM_NEW_CIPHER_TYPE[4] -char KM_WRITE_KEY_LENGTH[2] -char KM_WRITE_KEY_DATA[([0] << 8)|[1]] - -There are four possible values of KM_KEY_MGMT_TYPE: -KM_TYPE_FIXED_KEY (setting up the transmission of pre-encrypted data), -KM_TYPE_RESUME_KEY (used to end transmission of pre-encrypted data), -KM_TYPE_REDO_HANDSHAKE (triggering a new run of the handshake -protocol), and KM_TYPE_CLOSE_CONN (preceding the closure of a -connection). - -4.4.1 Preencrypted data - -A KM_KEY_MGMT_TYPE value of KM_TYPE_FIXED_KEY indicates that the key -management message contains a fixed encryption key with which -subsequent data records will be encrypted until further notice. -Using this type of key management message, a client or server can -send data that has been pre-encrypted and stored in encrypted form. -Note that pre-encrypted data can be pre-MAC'd as well. (See section -7.3.) Note also that a key management message of this type must not -be sent unless both client and server have indicated support for the -pre-encrypted data feature during the handshake phase associated with -this connection; see sections 5.2.1 and 5.2.2. - -In a message of type KM_TYPE_FIXED_KEY, KM_NEW_CIPHER_TYPE contains a -cipher type code, and KM_NEW_HASH_TYPE contains a hash function type -code (see sections 6.2 and 6.3, respectively). These types must be -supported by the receiver of this message, as indicated in during the -handshake phase for this connection. (See sections 5.2.1 and 5.2.2.) -The fixed encryption key (WRITE_KEY) is sent in the field -KM_WRITE_KEY_DATA. - -Note that the encryption and MAC calculation used for the key -management message itself, and for subsequent non-data records, are -not altered. However, subsequent data records in the same direction -are encrypted using the WRITE_KEY sent in the KM_WRITE_KEY_DATA -field, until a key management message of type KM_TYPE_FIXED_KEY or -KM_TYPE_RESUME_KEY is sent and received, or until the connection -closes. (Note that pre-encrypted data is not "nested"; a -KM_TYPE_FIXED_KEY message is treated as a KM_TYPE_RESUME_KEY message -immediately followed by a KM_TYPE_FIXED_KEY message.) - -4.4.2 Restoring original key - -A key management message of type KM_TYPE_RESUME_KEY restores the value -of the encryption key used for data records transmitted in the same -direction to the value originally negotiated during the handshake -phase of the current connection. This key is used until the -connection closes, or until a key management message of type -KM_TYPE_FIXED_KEY or KM_TYPE_REDO_HANDSHAKE is received. - -In this message, the KM_CIPHER_TYPE and KM_HASH_TYPE messages are set -to their original values negotiated during the handshake phase for -the current connection. (See section 5.2.2.) The remaining data -fields are empty, and their length is zero. - - -4.4.3 Closing connection - -If both client and server indicated support for the "closing -connection" feature during the handshake phase of the current -connection (see sections 5.2.1 and 5.2.2), then the connection is -"closure-monitored", and closure of a connection is handled in a -special way. Whenever a client or server is about to close a -closure-monitored connection without an error, at any point following -the completion of the handshake phase of the protocol, an exchange of -key management messages of type KM_TYPE_CLOSE_CONN is initiated -first. In both messages, the KM_NEW_CIPHER_TYPE and KM_NEW_HASH_TYPE -fields contain the current cipher and hash types, respectively, and -the remaining data fields are empty, with length zero. The sender of -one of these messages simply waits for a message of the same type to -be received in reply, then closes the connection; a receiver of such -a message who has not yet sent one replies with a message of the same -type, then closes the connection. A closure-monitored connection -closed without an error before receipt of a message of this type -results in a CONN_BROKEN error (see section 4.6). - - -4.4.4 Redo handshake - -If both client and server indicated support for the "redo handshake" -feature during the handshake phase of the current connection (see -sections 5.2.1 and 5.2.2), then the connection is "redo-enabled", and -either the client or the server may request, at any time after the -handshake phase has been completed for a connection, that another -handshake phase be performed for that connection. For example, -either party may request another handshake phase instead of closing -the connection in order to avoid allowing a sequence number to "wrap" -beyond 0xFFFFFFFF (see section 7.3). In addition, it is recommended -that implementations enforce limits on the duration of both -connections and sessions, with respect to the total number of bytes -sent, the number of records sent, the actual time elapsed since the -beginning of the connection or session, and, in the case of sessions, -the number of reconnections made. These limits serve to ensure that -keys are not used more or longer than it is safe to do so; hence the -limits may depend on the type and strength of cipher, key exchange and -authentication used, and may, at the implementer's discretion, include -indications from the application as to the sensitivity of the data -being transmitted or received. They may be enforced using closure of -the connection or (in a redo-enabled connection) "redo handshake" key -management messages. - -To request a new handshake phase for the current connection, the -sender (client or server) sends a key management message of type -KM_TYPE_REDO_HANDSHAKE. The KM_NEW_CIPHER_TYPE and KM_NEW_HASH_TYPE -fields contain the current cipher and hash types, respectively, and -the remaining data fields are empty, with length zero. - -There are several cases to consider to ensure that messages are -dealt with in the correct order. The following rules ensure that the -first messages in the redone handshake are always immediately preceded -by a "redo handshake" key management message. - -If the client initiates the "redo handshake", it sends the "redo -handshake" message immediately followed by a normal CLIENT_HELLO -handshake message; the server, on receiving the "redo handshake" -message, may be in one of two states. If the last message it sent -was a "redo handshake" message, then it simply waits for the -CLIENT_HELLO message; otherwise, it sends a "redo handshake" message -in response, and then waits for the CLIENT_HELLO message. - -If the server initiates the "redo handshake", then the server sends -the "redo handshake" message and simply waits for a "Redo Handshake" -message in response; this "redo handshake" message should be -immediately followed by a normal CLIENT_HELLO handshake message. The -client, on receiving the server's "redo handshake" message, may be in -one of two states. If the last two messages it sent were a "redo -handshake" message followed by a CLIENT_HELLO message, then it simply -waits for a SERVER_HELLO handshake message; otherwise, it sends a -"redo handshake" message in response, followed by a CLIENT_HELLO -message, and then waits for a SERVER_HELLO message. - -In all cases, the sender of the "redo handshake" message continues to -process incoming messages, but may not send any non-handshake messages -until the new handshake completes. If the connection is -closure-monitored (see section 4.4.3), then the sending of an -unprovoked "closing connection" key management message between the -sending of a "redo handshake" message and the completion of the -subsequent handshake is not permitted. However, in such connections -the sender of a "redo handshake" message must be prepared to receive a -"closing connection" message instead of a "redo handshake" message; in -this case the sender responds with a "closing connection" message and -closes the connection. - -The handshake phase that follows a "redo handshake" message exchange -is a normal one in most respects; the client may request the -reconnection of an old session or request that a new session be -initiated, and the server, on receiving a reconnection request, can -accept the reconnection or demand that a new session be initiated -instead. If a new session is being established, then both client and -server must request the same type of authentication requested in the -previous session; if one or the other was not authenticated in the -previous session, then requesting authentication from the -non-authenticated party in the new handshake phase is permitted. Both -parties must verify that the specifications negotiated previously in -the session (cipher type, key exchange type, certificate type and -certifier, hash function type, signature types, and so on), as well as -any certificates exchanged, are identical to those found in the new -handshake phase (with the exception of new types and certificates for -an authentication performed in this handshake, but not in the previous -one). A mismatch results in a SPECS_MISMATCH or BAD_CERTIFICATE -error (see section 4.6.) This ensures that the security properties -of the communication channel do not change for the worse. - - -4.5 Data messages - -Data messages contain user data to be delivered back to the -application using PCT. Each data record or datagram record contains -exactly one data message (corresponding to the ACTUAL_DATA field -in the description of these records), and data messages are never -continued across multiple messages. - -PCT version 2 Data messages have the following format: - -char DM_MESSAGE_TYPE[2] -char DM_MESSAGE_DATA[MESSAGE_LENGTH] - -The only defined MESSAGE_TYPE in PCT version 2 is DM_TYPE_USER_DATA; -the data in messages of this type is presented directly to the -application. However, implementations of PCT can assign types to -other values to indicate types of preprocessing, such as particular -compression/decompression algorithms, to be performed before passing -the data in MESSAGE_DATA to the application. Such implementations -should allow messages to be nested in the obvious way, with each -preprocessing step yielding another data message of the correct -format, and the last step yielding a data message of type -DM_TYPE_USER_DATA. The permissible message types for a particular -connection are negotiated during the handshake phase; see sections -5.2.1 and 5.2.2. An unrecognized message type results in an -ILLEGAL_MESSAGE error (see section 4.6). - -For message type DM_TYPE_USER_DATA, the DM_MESSAGE_DATA field -contains user data to be passed to the application. For other -message types, DM_MESSAGE_DATA contains data which, after the -preprocessing determined by the message type, yields another data -message. MESSAGE_LENGTH (for the data message directly contained in -the data or datagram record) is calculated as ACTUAL_LENGTH - 2, or -RECORD_LENGTH - ENCRYPTED_KEY_LENGTH - MAC_LENGTH - 6 if the message -is contained in a datagram record and RECORD_LENGTH - MAC_LENGTH - 4 -if it is contained in a data record. - -4.6 Error messages - -Error handling in the PCT protocol is very simple. When an error is -detected before a connection is closed, the detecting party sends a -message to the other party indicating the error so that both parties -will know about it, and then closes the connection. In the case of -closure-monitored connections (see section 4.4.3), the error message -replaces the "closing connection" key management message. Receiving -an error message also causes the receiving party to close the -connection. (No "closing connection" message is ever sent in reply to -an error message before closure.) - -Servers and clients should not make any further use of any keys, -challenges, connection identifiers, or session identifiers associated -with a connection aborted due to an error. It is recommended that -implementations perform some kind of alert or logging function when -errors are generated to facilitate monitoring of various types of -attack on the system. - -Error messages have the following format: - -char ER_ERROR_TYPE[2] -char ER_ERROR_INFO_LENGTH[2] -char ER_ERROR_INFO_DATA[([0] << 8)|[1]] - -The ERROR_INFO_LENGTH field is zero except in the case of the -SPECS_MISMATCH error message, which has a two-byte ERROR_INFO_DATA -field. Note that when an error message is sent before the end of -the handshake phase of the protocol, the record containing it is left -unencrypted, and its MAC is omitted. - -The following errors are defined in PCT version 2: - -PCT_ERR_BAD_CERTIFICATE - -This error occurs when the client or server receives a handshake -message in which a key-exchange public key certificate is invalid, -either because one or more of the signatures in the certificate is -invalid, or because the identity or attributes on the certificate -are in some way incorrect. - -PCT_ERR_CLIENT_AUTH_FAILED - -This error occurs when the server receives a CLIENT_MASTER_KEY or -CLENT_VERIFY message from the client in which the client's -authentication response is incorrect. The certificate may be -invalid, the signature may be invalid, or the contents of the signed -response may be incorrect. - -PCT_ERR_CONN_BROKEN - -This error occurs when a closure-monitored connection (see section -4.4.3) is closed without an error message or a "closing connection" -key management message having been received. Since this error only -occurs after a connection has been closed, no error message is sent. - -PCT_ERR_ILLEGAL_MESSAGE - -This error occurs under a number of circumstances. For example, it -occurs when an unrecognized handshake message is encountered, or when -the value of CH_OFFSET is to large for its CLIENT_HELLO message. - -PCT_ERR_INTEGRITY_CHECK_FAILED - -This error occurs when either the client or the server receives a -record in which the MAC_DATA is incorrect. It is also recommended -that such a record be treated as if had not been received, in order -to ensure that applications do not receive and process invalid data -before learning that it has failed its integrity check. - -PCT_ERR_SERVER_AUTH_FAILED - -This error occurs when the client receives a SERVER_HELLO or -SERVER_VERIFY message in which the authentication response is -incorrect. - -PCT_ERR_SPECS_MISMATCH - -This error occurs when a server cannot find a cipher, hash function, -certificate type, or key exchange algorithm it supports in the lists -supplied by the client in the CLIENT_HELLO message. This error may -also occur as a result of a mismatch in cipher specifications or -client authentication requests between the initial specifications and -those that resulted from a redo handshake sequence. - -The error message for this error includes a two-byte informational -field, with eight flags defined as follows: - -SPECS_MISMATCH_CIPHER = 0x0001 -SPECS_MISMATCH_HASH = 0x0002 -SPECS_MISMATCH_EXCH = 0x0004 -SPECS_MISMATCH_SIG = 0x0008 -SPECS_MISMATCH_CERT = 0x0010 -SPECS_MISMATCH_CERTIFIER = 0x0020 -SPECS_MISMATCH_COMBINATION = 0x0040 - -Each flag is set if and only if the corresponding list resulted in -a mismatch. For example, if and only if the SPECS_MISMATCH error -message is being sent because server failed to find a certificate -type it supports in the list supplied by the client in the -CH_CERT_LIST_DATA field, then the SPECS_MISMATCH_CERT flag in -the error message would be non-zero. The SPECS_MISMATCH_COMBINATION -flag indicates that while there were matches found in each -individual category, all available certificates were incompatible -with all the type entries in at least one of the relevant lists -(CH_CERT_LIST_DATA, CH_CERTIFIER_LIST_DATA, CH_EXCH_LIST_DATA and -CH_SIG_LIST_DATA). - - -5. PCT Handshake Phase - -5.1 PCT handshake protocol overview - -5.1.1 PCT handshake protocol introduction - -The PCT Handshake Protocol (version 2) is performed during the -handshake phase at the start of every connection, and is used to -negotiate security enhancements (authentication, symmetric -encryption, and message integrity) to data sent during the rest of -the connection. - -The version 2 PCT Handshake Protocol consists of five messages, sent -respectively by the client, then server, then client, then server, -then client, in that order. (Moreover, under certain circumstances, -some or all of the last three messages are omitted.) The messages -are named, in order, CLIENT_HELLO, SERVER_HELLO, CLIENT_MASTER_KEY, -SERVER_VERIFY, and CLIENT_VERIFY. - -The general contents of these messages depend upon two criteria: -how/if a "master key" for the session is to be exchanged, and how/if -each of the client and server are to be authenticated. At least one -of the two must be authenticated by some means; authentication of -either--or both--may be based on either a key exchange, a digital -signature, or (for one of the two) a previously shared "password" -key, or, in the case of a connection in the same session as a -previous one, on a "master key" shared previously in the session. - -The first criterion is determined by the client and server together: -first, the CLIENT_HELLO message may contain a request to "reconnect" -using a previously shared master key from a particular session (in -which case no new key exchange is necessary). The SERVER_HELLO -message will either confirm a requested continuation of the session -through the new connection, or require that a new session be -initiated, with a new key exchange. PCT version 2 supports -RSA {TM} -based key exchange (see [14], [3]), Diffie-Hellman key -exchange (see [4], [15]) and FORTEZZA KEA token key exchange. The -chosen key exchange is used by client and server in the case of a new -session to obtain a new shared master key. This master key is used to -derive keys for encryption and message integrity (or "message -authentication") for the connection and for other connections -associated with the same session. Note that key exchanges have an -implicit associated direction, with a master key being, in effect, -sent from one party to the other (literally in the case of RSA key -exchange, and more metaphorically in the case of -Diffie-Hellman/FORTEZZA KEA key exchange). Hence a direction must -also be chosen for the exchange. In fact, the parties may agree to -perform two key exchanges, one in each direction; in that case, the -master key for the session is computed using both of the sent keys. -In this document, the term "encrypted master key" refers either to an -RSA-encrypted master key, or to the second (typically uncertified) -Diffie-Hellman/FORTEZZA KEA public value sent in a Diffie-Hellman or -FORTEZZA KEA key exchange. The key exchange is said to be directed -towards the receiver of this encrypted master key. - -The second criterion is determined in a similar fashion: if the -connection is the first of a new session, then the client may request -authentication of the server by key exchange, or by digital signature, -or by private password, or by any one of a specified subset of these -options. The client also offers the server a choice among the client -authentication options (from among these choices) available. The -server, in turn, selects a preferred authentication method if a choice -is offered, and may make a similar request from among the client -authentication options offered. All these authentications are "linked" -to the key exchange performed during the handshake, so that not only -the identity of the authenticated party, but also that party's -association to the handshake's key exchange as performed, is verified. - -If no key exchange is performed, then both client and server are -authenticated using the shared master key for the reconnected session, -rather than any of the methods described above. - -In addition to key exchange and authentication, the handshake protocol -performs two other tasks: negotiation of cryptographic parameters, -and handshake verification. The first is accomplished by the -CLIENT_HELLO and SERVER_HELLO messages. The CLIENT_HELLO includes a -list of codes for acceptable types of symmetric cipher and -cryptographic hash function for use during the session, as well as -key exchange and signature algorithms, certificate types and -certifiers, and authentication methods acceptable for use during the -handshake protocol. The server responds in the SERVER_HELLO message -with its choices from among these lists of acceptable types. The -second task is performed during the first authentication; it is based -on a cryptographic hash of all the handshake message data passed up to -that point. Verification of this authenticated hash value by its -receiver assures that the handshake was not tampered with in transit. - - -5.1.2 PCT handshake authentication - -The four types of authentication permissible in PCT version 2 are -key-exchange, digital signature, private password, and reconnection. -Each follows a particular protocol flow, which is essentially -independent of which party is being authenticated (except regarding -the assignment of roles to the client and server). In each case, -client and server both issue random challenges (in the CLIENT_HELLO -and SERVER_HELLO messages, respectively); these challenges, and -all information exchanged up to and including the completion of -the key exchange(s), are incorporated into an authentication -response by the party being authenticated (the "responder", as -opposed to the "challenger", to whom the response is sent). Hence -the authentication response cannot be sent until the sending of both -challenges, as well as the key exchange(s), have been completed -(although it may appear in the last message which contributes to one -of these). - -In key-exchange-based authentication, the responder sends a certified -public key, which the authenticating party (the "challenger") uses to -send a master key. In the case of Diffie-Hellman/FORTEZZA KEA key -exchange, the challenger's value is normally randomly chosen, whereas -the responder's is fixed and certified; the master key computed by -the challenger can also be derived using the responder's private key -and the challenger's sent value. In the case of RSA key exchange, the -master key is randomly chosen at the time of the key exchange by the -challenger and encrypted using the responder's certified public key. -The responder then combines the received master key (which may first -be combined with another sent master key, in the case of two-way key -exchange) with all handshake message data sent so far, including both -challenges and all of the key exchange data, to compute a response. -This response is in the form of a keyed hash, which is verified by the -challenger to confirm that the responder could derive the master key -correctly, and therefore holds the correct private key. (A keyed hash -is simply the application of a cryptographic hash function to a key -and some other input data; the assumed properties of the hash function -make the function result for any other data input infeasible to -compute for anyone not possessing the key.) - -A key-exchange-based authentication therefore has the following -message flow: - -Challenger Responder ----------- --------- - -Challenger's Responder's -Challenge Challenge - - [Certified public - key-exchange key] - -Random encrypted -master key/public -Diffie-Hellman value - - Keyed hash response - - -The challenges always appear in the CLIENT_HELLO and SERVER_HELLO -messages. The certified key may not need to be sent, if the -responder already possesses it (perhaps from a previous session). - -In signature-based authentication, the responder simply sends a -certified digital signature public key, accompanied by a digital -signature, using the associated private key, of a cryptographic hash -of all handshake messages up to the one being sent. (Note that this -value is therefore derived from the completed key exchange, as well -as both challenges). The challenger verifies the signature using -the responder's certified public key. A signature-based -authentication has the following message flow: - -Challenger Responder ----------- --------- - -Challenger's Responder's -Challenge Challenge - - Key Exchange(s) - - Certified public - signature key, - signature response - -Again, the challenge messages always appear in the CLIENT_HELLO and -SERVER_HELLO messages. The public key certificate may not be -necessary, but is sent regardless, since it can accompany the -digital signature in the same message, and therefore has no cost in -extra messages. A certificate-identifying code may be used in its -place if understood by both parties; see section 6.4. - -Password-based authentication is similar to signature-based -authentication; the exchanged master key is combined with the -shared password and all the handshake message data sent so far, -including the identity of the responder, the exchanged master key -and both challenges, to produce a keyed hash response which is sent -by the responder and verified by the challenger. - -A special case of this authentication is a doubly-certified -Diffie-Hellman key exchange, in which one party is authenticated by -certified Diffie-Hellman key-exchange public key, and the challenger's -sent value is not random but rather another certified Diffie-Hellman -public key. In this case, the challenger's identity is represented -by the certificate for the public value sent, and the exchanged -master key received by the responder is also treated simultaneously -as the challenger's password. (If both parties are to be -authenticated by certified Diffie-Hellman key exchange, then each -sends a randomly chosen public value to the other, and the final -master key is obtained by combining the two keys exchanged.) - -It is recommended that shared private keys used for password-based -authentication be machine-generated and cryptographically random in -the same sense as the master key (see section 6.1.3). However, -because the distribution of password-style shared private keys is -outside the scope of this protocol, and is therefore vulnerable to -possible insecure implementations, the following constraints on -password-based authentication are imposed: - -1. Only one of the client and server, not both, may be -authenticated using password-based authentication. - -2. Password-based authentication may only be used if the other party -is also authenticated, using either key exchange- or signature-based -authentication. - -3. If the other party is authenticated using signature-based -authentication, then the password-based authentication response must -be sent only after the other party's authentication response has been -sent and verified. - -These constraints protect poorly chosen password-style shared private -keys from off-line brute force attacks. However, even a well-chosen -shared private key is vulnerable if not kept strictly confidential -by both parties sharing it. Implementations must therefore ensure -this confidentiality. Poorly-chosen or poorly-guarded passwords are -of course still vulnerable to other attacks. - -A password-based authentication has the following message flow: - -Challenger Responder ----------- --------- - -Challenger's Responder's -Challenge Challenge - - Key Exchange(s) - - responder's identity/ - certified D-H public - value, keyed hash response - - -Finally, in the case of authentication based on a master key exchanged -earlier in the session, the response is computed from both challenges, -the shared master key, and the session identifier. (The client's -response is in fact implicit; by computing a correct MAC for its first -data message, the client demonstrates its possession of the session's -master key.) This authentication has the following flow: - -Challenger Responder ----------- --------- - -Challenger's Responder's -Challenge Challenge - - keyed hash response - - -5.1.3 Handshake key exchange - -In the full handshake protocol, authentications are interleaved with -at least one key exchange (and with each other, if both client and -server are being authenticated). The interleaving is designed to -compress the authentications and key exchange(s) into as few -messages as possible. For example, a client has the option of -sending an encrypted public key and/or (possibly certified) -key-exchange public key in the CLIENT_HELLO message, along with its -challenge. The latter allows the client to "receive" a -client-directed key exchange, while the former initiates a -server-directed key exchange. However, the client may not have the -server's key-exchange public key, and may not anticipate a request for -a client-directed key exchange; hence, sending of the encrypted master -key and/or client key-exchange certificate may be postponed to the -CLIENT_MASTER_KEY message. - -In general, each possible key exchange has a "regular" and "quick" -flow. A client-directed key exchange may occur beginning in the -CLIENT_MASTER_KEY message, when the client sends a (possibly -certified) key-exchange public key, then continues in the -SERVER_VERIFY message with the server sending an encrypted master -key. In the quick version, the client may (or may not) send the -(certified) public key in the CLIENT_HELLO message, and the server, -upon receiving it (or having received it at some time in the past) -sends an encrypted master key in the SERVER_HELLO message. Similarly, -normal server-directed key exchange begins in the SERVER_HELLO message -with a (possibly certified) key-exchange public key, and continues -with an encrypted master key in the following CLIENT_MASTER_KEY -message. In the quick version, the client, having received the -server's public key previously, sends an encrypted master key -immediately, in the CLIENT_HELLO message. - -5.1.4 PCT Handshake Protocol flow - -The contents of PCT version 2 handshake protocol can be summarized as -follows: - -The CLIENT_HELLO message contains a random authentication challenge -to the server and a request for the type and level of cryptography, -certification, authentication and (if necessary) digital signature -to be used for the session, if it is to be a new one. If the client -is attempting to continue an old session, then it also supplies that -session's identifier. The client can also send a "quick -certificate", in anticipation of a client authentication request from -the server, and even a "quick master key", if the client already has -a satisfactory server's key-exchange public key. - -If the server accepts the old session identifier, then the -SERVER_HELLO message contains a response to the client's challenge, -and a random connection identifier which doubles as a random challenge -to the client. The handshake is then finished (although an -authentication of the client is implicit in the MAC included with the -client's first data message). - -In the case of a new session, the SERVER_HELLO message contains a -random connection identifier; this identifier doubles as an -authentication challenge to the client if the server desires client -authentication. The server also responds with its choices for type -and level of cryptography, certification, authentication and (if -necessary) digital signature (from among those offered by the -client). In addition, the server sends a certificate for the type of -authentication requested by the client (if any), and sends a "quick -master key" and/or "quick response" in response to the client's -"quick certificate" and/or "quick master key", respectively, if -appropriate. In the latter case, the response may require an -accompanying digital signature public-key certificate or "identity -indicator" (directing the client to the correct shared password), -and the handshake protocol completes at this point if no client -authentication is required. - -The CLIENT_MASTER_KEY message sent by the client (assuming that it -is necessary) includes a (possibly certified) key-exchange public key, -if requested by the server. It also contains an encrypted master key, -if the server sent a key-exchange public key, and an authentication -response (accompanied by an identity indicator or digital signature -public key certificate, if appropriate) if client authentication by -signature or password was requested, and the key exchange has been -completed. If the server's authentication response has also been -received (or was not required), then the handshake protocol completes -at this point. - -The SERVER_VERIFY message sent next by the server, if necessary, -contains an encrypted master key sent to the client, if requested, -and/or an authentication response (possibly accompanied by a digital -signature public key certificate or identity indicator) to the -encrypted master key sent in the previous message. Unless the former -requires an authentication response, the protocol completes at this -point. - -Finally, the CLIENT_VERIFY message, if needed, contains the client's -authentication response to the key exchange completed by the -encrypted master key sent in the SERVER_VERIFY message. - -Usually the client or server can safely begin sending data records -on the underlying transport immediately following its own last -handshake message, without waiting for a response even if one is -expected. In most instances, therefore, PCT adds only a single -round-trip to the connection's setup cost. Sometimes the cost is -even less; for instance, a server can begin sending data immediately -after sending the SERVER_HELLO message if the client initiated a -quick server-directed key exchange and only server authentication -is required, or if a successful reconnection of an established -session has occurred (note that in this case the client cannot send -data until receiving the SERVER_HELLO message containing the server's -challenge). - - -5.2 PCT Handshake messages - -PCT version 2 Handshake messages are sent in handshake records, whose -format is described in section 4.3.1. These records are sent in the -clear (unencrypted), although some of the key-exchange-related fields -involve (public-key) encryption. A single handshake message may span -across more than one handshake record; however, only data fields -associated with four-byte length fields may do so. These fields are -always the last ones in a message; the remaining ones (including all -length fields) must be contained within the first handshake record -used for the handshake message. (Note that for PCT version 1 -compatibility reasions, the CLIENT_HELLO message has no such fields.) - -5.2.1 CLIENT_HELLO - -char CH_SESSION_ID_DATA[30] -char CH_CHALLENGE_DATA[30] -char CH_CLIENT_VERSION[2] -char CH_OFFSET[2] -char CH_CIPHER_LIST_LENGTH[2] -char CH_HASH_LIST_LENGTH[2] -char CH_CERT_LIST_LENGTH[2] -char CH_EXCH_LIST_LENGTH[2] -char CH_KEY_ARG_LENGTH[2] -char CH_MSG_LIST_LENGTH[2] -char CH_SIG_LIST_LENGTH[2] -char CH_CERTIFIER_LIST_LENGTH[2] -char CH_QUICK_PUBLIC_VALUE_LENGTH[2] -char CH_QUICK_SERVER_PUBLIC_VALUE_LENGTH[2] -char CH_QUICK_ENCRYPTED_KEY_LENGTH[2] -char CH_AUTH_OPTIONS[2] -char CH_CIPHER_LIST_DATA[([0] << 8)|[1]] -char CH_HASH_LIST_DATA[([0] << 8)|[1]] -char CH_CERT_LIST_DATA[([0] << 8)|[1]] -char CH_EXCH_LIST_DATA[([0] << 8)|[1]] -char CH_KEY_ARG_DATA[([0] << 8)|[1]] -char CH_MSG_LIST_DATA[([0] << 8)|[1]] -char CH_SIG_LIST_DATA[([0] << 8)|[1]] -char CH_CERTIFIER_LIST_DATA[([0] << 8)|[1]] -char CH_QUICK_PUBLIC_VALUE_DATA[([1] << 8)|[1]] -char CH_QUICK_SERVER_PUBLIC_VALUE_DATA[([0] << 8)|[1]] -char CH_QUICK_ENCRYPTED_KEY_DATA[([0] << 8)|[1]] - -When a client first connects to a server it is required to send the -CLIENT_HELLO message. The server is expecting this message from the -client as its first message. It is an ILLEGAL_MESSAGE error for a -client to send anything else as its first message. The CLIENT_HELLO -message begins with two fixed-length fields followed by a two-byte -version number and an offset to the variable length data. The -version number field CH_CLIENT_VERSION is always set to -PCT_VERSION_V2 in PCT version 2. The CH_OFFSET field contains the -number of bytes used by the various fields (length fields plus the -AUTH_OPTIONS field) that follow the offset field and precede the -variable-length fields. For PCT version 2, this offset value is -always PCT_CH_OFFSET_V2, i.e., 24. However, inclusion of this field -will allow future versions to be compatible with version 2, even if -the number of these fields changes, just as inclusion of this field -helps make PCT version 2 CLIENT_HELLO messages understandable to PCT -version 1 servers. - -The CH_CHALLENGE_DATA field is a string of 30 bytes of random bits, to -be used as authentication challenge data from the client. The -CHALLENGE_DATA should be cryptographically random, in the same sense -as the MASTER_KEY (see section 6.1.3). If the client finds a -session identifier in its cache for the server, then that -session-identifier data is sent in the field CH_SESSION_ID_DATA. -Otherwise, the special PCT_SESSION_ID_NONE value is used. In either -case, the client specifies in CIPHER_LIST_DATA, HASH_LIST_DATA, -EXCH_LIST_DATA and SIG_LIST_DATA its preferred choices of symmetric -cipher, key lengths, hash function, asymmetric key exchange algorithm -and digital signature algorithm. However, if a session identifier is -sent, then these choices are only relevant in the case where the -server cannot recognize the session identifier, and a new session -must therefore be initiated. If the server recognizes the session, -then these fields are ignored by the server. Similarly, if the -client requires server authentication in the event of a new session -initiation, then the CERT_LIST_DATA and CERTIFIER_LIST_DATA lists -contain the client's preferred choices of certificate type and -certifier; otherwise, these lists are empty, and their length is -zero. Finally, the MSG_LIST_DATA list contains a list of data -message types (other than the DM_TYPE_USER_DATA) supported by the -client; if the client supplies a session identifier and the server -recognizes it, then this list is ignored, and the list negotiated -previously in the session is used instead. - -The AUTH_OPTIONS field contains the values of twelve flags that -determine the flow of the remainder of the protocol if a new session -is being initiated. The flags are associated with the twelve -low-order bits of the AUTH_OPTIONS field, and are named, in order -(from least to most significant bit), as follows: - -CH_DEMAND_KEY_EXCH_SEND := 0x0001 -CH_DEMAND_AUTH_KEY_EXCH := 0x0002 -CH_DEMAND_AUTH_SIG := 0x0004 -CH_DEMAND_AUTH_PASSWORD := 0x0008 -CH_OFFER_KEY_EXCH_RECEIVE := 0x0010 -CH_OFFER_AUTH_KEY_EXCH := 0x0020 -CH_OFFER_AUTH_SIG := 0x0040 -CH_OFFER_AUTH_PASSWORD := 0x0080 -CH_REQUEST_RECONNECT := 0x0100 -CH_REQUEST_CLOSURE_MON := 0x0200 -CH_REQUEST_REDO_ENABLE := 0x0400 -CH_OFFER_CERTIFIER_TRYOUT := 0x0800 - -If the CH_DEMAND_KEY_EXCH_SEND flag is set to one, then the client -requires that the server accept an encrypted master key from the -client as part of the key exchange. If the CH_OFFER_KEY_EXCH_RECEIVE -flag is set to one, then the client is willing to receive an encrypted -master key from the server as part of the key exchange. If both flags -are set, then both conditions hold; the client requires that the -server receive a key exchange, and will also accept one, at the -server's option. In the case of uncertified Diffie-Hellman/FORTEZZA -KEA key exchange, the flags simply refer to the "receiver" sending the -public value first, followed by the "sender"; in other cases, the -holder of the private key associated with the RSA public key or -certified Diffie-Hellman/FORTEZZA KEA public value is always the -"receiver". (Doubly certified Diffie-Hellman/FORTEZZA KEA key -exchange is discussed in section 5.1.2.) Note that both client and -server are assumed willing to be the (possibly sole) sender of an -encrypted master key; hence, even if the CH_DEMAND_KEY_EXCH_SEND flag -is set to zero, and the CH_OFFER_KEY_EXCH_RECEIVE flag is set to one, -the client has neither ruled out being the sender, nor demanded to be -the receiver, of an encrypted master key. - -The six AUTH flags refer to types of authentication: the client -requires the server to authenticate by one of the means for which the -associated CH_DEMAND_AUTH flag is set to one, and offers to -authenticate itself, at the server's option, by any of the means for -which the associated CH_OFFER_AUTH flag is set to one. (The -abbreviations "KEY_EXCH", "SIG" and "PASSWORD" stand for -key-exchange-based, digital signature-based and shared password-based -authentication, respectively.) The settings of the flags must be -consistent with at least one key exchange and one authentication -occurring; i.e., at least one of the six authentication flags and at -least one of the two key exchange flags must be set to one. Moreover, -the constraints on password-based authentication must be obeyed. (See -sections 5.1.2 and 7.2.) - -The CH_REQUEST_RECONNECT flag indicates, when set to one, that the -client is requesting that the current connection be part of an -existing session; in this case, the CH_SESSION_ID field must contain -that session's identifier. The CH_REQUEST_CLOSURE_MON flag -indicates, when set to one, that the client wishes the current session -to be closure-monitored (see section 4.4.3). The -CH_REQUEST_REDO_ENABLE flag indicates, when set to one, that the -client wishes the current session to be redo-enabled (see section -4.4.4). Finally, the CH_OFFER_CERTIFIER_TRYOUT flag indicates, when -set to one, that the list of acceptable certifiers in -CH_CERTIFIER_LIST is not exhaustive (see below). - -The CIPHER_LIST_DATA field contains a list of possible symmetric -ciphers supported by the client, in order of (the client's) -preference. Each element in the list is a four-byte field, of which -the first two bytes contain a code representing a cipher type, the -third byte contains the encryption key length in bits (0-255), and the -fourth byte contains the MAC key length in bits, minus 64 (values -0-255, representing lengths 64-319; this encoding enforces the -requirement that the MAC key length be at least 64 bits). The entire -list's length in bytes (four times the number of elements) is placed -in CIPHER_LIST_LENGTH. - -The HASH_LIST_DATA field contains a list of possible hash functions -supported by the client, in order of (the client's) preference. The -server will choose one of these to be used for computing MACs and -deriving keys. Each element in the list is a two-byte field -containing a code representing a hash function choice. The entire -length of the list (twice the number of elements) is placed in -HASH_LIST_LENGTH. - -The CERT_LIST_DATA field contains a list of possible certificate -formats supported by the client, in order of (the client's) -preference. Each element in the list is a two-byte field containing a -code representing a certificate format. The entire length of the list -(twice the number of elements) is placed in CERT_LIST_LENGTH. - -The EXCH_LIST_DATA field contains a list of possible asymmetric key -exchange algorithms supported by the client, in order of (the -client's) preference. Each element in the list is a two-byte field -containing a code representing a key exchange algorithm type. The -entire length of the list (twice the number of elements) is placed -in EXCH_LIST_LENGTH. - -The KEY_ARG_DATA field contains an initialization vector to be used in -a reconnected session when the cipher type is a block cipher (see -section 6.1.5). If a new session is being requested (i.e., if the -CH_REQUEST_RECONNECT flag is set to zero), then KEY_ARG_LENGTH must -be zero. - -The MSG_LIST_DATA field contains a list of data message types (other -than DM_TYPE_USER_DATA) supported by the client. Each element in the -list is a two-byte field containing a code representing a data message -type. The entire length of the list (twice the number of elements) is -placed in MSG_LIST_LENGTH. - -The SIG_LIST_DATA field contains a list of possible signature -algorithms supported by the client, in order of (the client's) -preference. Each element in the list is a two-byte field containing -a code representing a signature algorithm type. The entire length -of the list (twice the number of elements) is placed in -SIG_LIST_LENGTH. - -The CERTIFIER_LIST_DATA field contains a list of identifiers of -possible certificate sources recognized by the client, in order of -(the client's) preference. Each element in the list is a -zero-delimited string. The entire length of the list is placed in -CERTIFIER_LIST_LENGTH. A client may indicate, by setting the -CH_OFFER_CERTIFIER_TRYOUT flag to one, that the certifier list does -not imply rejection of all other certifiers; for example, the client -may provide an abbreviated (or even empty) certifier list to avoid -constructing an exhaustive list of accepted certifiers, or may lack -a naming convention for certifiers known to be compatible with that -of the server. The client may still in that case reject a -certificate offered by the server. - -The CH_QUICK_PUBLIC_VALUE_DATA field may, at the client's option, -contain a (possibly certified) key-exchange public key. If the -field is non-empty, then the CH_OFFER_KEY_EXCH_RECEIVE flag must -be set to one. If the CH_OFFER_AUTH_KEY_EXCH flag is also set to -one, then the CH_QUICK_PUBLIC_VALUE_DATA field, if non-empty, -contains a certificate (including key-exchange public key); otherwise -the field, if non-empty, contains an uncertified key exchange public -value. The exact format of this field is described in section -6.1.2. If the client expects the server to demand client -authentication by key exchange, then this public key/certificate may -expedite the expected key exchange/authentication; however, the server -may still indicate in the subsequent SERVER_HELLO message that a -public key or certificate of another type (or from a different -certifier) is required. - -The CH_QUICK_SERVER_PUBLIC_VALUE_DATA and CH_QUICK_ENCRYPTED_KEY_DATA -fields may, at the client's option, contain, respectively, the public -value from a key-exchange public key certificate attributed to the -server, and an encrypted master key (or Diffie-Hellman/FORTEZZA KEA -public value) decryptable by the holder of the private key associated -with the certified key-exchange public key. The format of these -fields is described in section 6.1.2. If the client already -possesses a certified key-exchange public key belonging to the server, -then use of these fields will expedite the resulting key exchange. -However, in unusual circumstances, the server may still "disavow" the -key exchange--that is, refuse to receive it, and offer only some -other key exchange type, direction or certificate. (For example, the -public key used by the client may be incorrect or out-of-date.) Note -that if these fields are used by the client, then the -CH_REQUEST_KEY_EXCH_SEND flag must be set to one. - -The server, on receiving a CLIENT_HELLO message, checks the version -number and the offset field to determine where the variable-length -data fields start. (The OFFSET value should be at least -PCT_CH_OFFSET_V2 for versions 2 and higher.) The server then checks -whether the CH_REQUEST_RECONNECT flag is set to one, and if so, -whether it recognizes the SESSION_ID. In that case, the server -responds with a SERVER_HELLO message with the SH_ACCEPT_RECONNECT -flag set, and the appropriate values (see below) in the RESPONSE and -CONNECTION_ID fields. - -Otherwise, it examines the CIPHER_LIST and HASH_LIST lists in the -CLIENT_HELLO message to select a cipher and hash function. The -server also examines the AUTH_OPTIONS flags and CERT_LIST, -CERTIFIER_LIST, SIG_LIST and EXCH_LIST lists to select a key -exchange type and direction(s) and an authentication combination for -itself (including authentication type, certificate type and -certifier) which is acceptable to both the client and the server, if -one or more of the CH_DEMAND_AUTH flags were set. Finally, the -server examines the same lists to choose a sublist from each with -which it is compatible, if it requires client authentication as well. -If such selections are possible, then the server sends a SERVER_HELLO -message to the client as described below; otherwise, the server -detects a SPECS_MISMATCH error. The server also examines the quick -key-exchange public value (if sent) for compatibility, and/or -decrypts the quick encrypted master key, if possible. - - -5.2.2 SERVER_HELLO - -char SH_SERVER_VERSION[2] -char SH_AUTH_OPTIONS[2] -char SH_CIPHER_SPECS_DATA[4] -char SH_HASH_SPECS_DATA[2] -char SH_EXCH_SPECS_DATA[2] -char SH_CONNECTION_ID_DATA[30] -char SH_SESSION_ID_DATA[30] -char SH_ALT_CIPHER_LIST_LENGTH[2] -char SH_ALT_HASH_LIST_LENGTH[2] -char SH_MSG_LIST_LENGTH[2] -char SH_EXCH_LIST_LENGTH[2] -char SH_CERT_LIST_LENGTH[2] -char SH_SIG_LIST_LENGTH[2] -char SH_QUICK_ENCRYPTED_KEY_LENGTH[2] -char SH_RESPONSE_LENGTH[2] -char SH_CERTIFIER_LIST_LENGTH[4] -char SH_PUBLIC_VALUE_LENGTH[4] -char SH_SIG_CERT_LENGTH[4] -char SH_ALT_CIPHER_LIST_DATA[([0] << 8)|[1]] -char SH_ALT_HASH_LIST_DATA[([0] << 8)|[1]] -char SH_MSG_LIST_DATA[([0] << 8)|[1]] -char SH_EXCH_LIST_DATA[([0] << 8)|[1]] -char SH_CERT_LIST_DATA[([0] << 8)|[1]] -char SH_SIG_LIST_DATA[([0] << 8)|[1]] -char SH_QUICK_ENCRYPTED_KEY_DATA[([0] << 8)|[1]] -char SH_RESPONSE_DATA[([0] << 8)|[1]] -char SH_CERTIFIER_LIST_DATA[([0] << 24)|([1] << 16)|([2] << 8)|[3]] -char SH_PUBLIC_VALUE_DATA[([0] << 24)|([1] << 16)|([2] << 8)|[3]] -char SH_SIG_CERT_DATA[([0] << 24)|([1] << 16)|([2] << 8)|[3]] - -The server sends this message after receiving the client's -CLIENT_HELLO message. The PCT version number in SH_SERVER_VERSION -is always the maximum protocol version that the server supports; the -remainder of the SERVER_HELLO message and all subsequent messages -will conform to the format specified by the protocol version -corresponding to the minimum of the client and server protocol -version numbers, as indicated by the CH_CLIENT_VERSION and -SH_SERVER_VERSION fields. Unless there is an error, the server always -returns a random value 30 bytes in length in the CONNECTION_ID field. -This value doubles as challenge data if the server requests client -authentication, and should therefore be random in the same sense as -the challenge data in the CLIENT_HELLO message. - -The SH_AUTH_OPTIONS field contains twelve flags, associated with the -twelve low-order bits of the SH_AUTH_OPTIONS field; they are named, -in order (from least to most significant bit), as follows: - -SH_ACCEDE_KEY_EXCH_RECEIVE := 0x0001 -SH_ACCEDE_AUTH_KEY_EXCH := 0x0002 -SH_ACCEDE_AUTH_SIG := 0x0004 -SH_ACCEDE_AUTH_PASSWORD := 0x0008 -SH_ACCEPT_KEY_EXCH_SEND := 0x0010 -SH_ACCEPT_AUTH_KEY_EXCH := 0x0020 -SH_ACCEPT_AUTH_SIG := 0x0040 -SH_ACCEPT_AUTH_PASSWORD := 0x0080 -SH_ACCEPT_RECONNECT := 0x0100 -SH_ACCEPT_CLOSURE_MON := 0x0200 -SH_ACCEPT_REDO_ENABLE := 0x0400 -SH_OFFER_CERTIFIER_TRYOUT := 0x0800 - -The SH_ACCEPT_CLOSURE_MON flag is set to one if and only if the -CH_REQUEST_CLOSURE_MON flag is set to one, and the server also -prefers the current connection to be closure-monitored (see section -4.4.3). The SH_ACCEPT_REDO_ENABLE flag is set to one if and only if -the CH_REQUEST_REDO_ENABLE flag is set to one, and the server also -prefers the current connection to be redo-enabled (see section 4.4.4). - -If the server recognizes the contents of the CH_SESSION_ID_DATA -field of the CLIENT_HELLO message as session identifier for a session -for which the master key is still available to the server, then the -SH_ACCEPT_RECONNECT flag in the SH_AUTH_OPTIONS field is set to one. -Also, the SH_SESSION_ID_DATA field echoes the CH_SESSION_ID_DATA -field. Moreover, the server sets the CIPHER_SPECS_DATA and -HASH_SPECS_DATA fields to the values stored along with the session -identifier. There are two subcases: (1) If the SH_EXCH_SPECS_DATA -value does not refer to a TOKEN type (see section 6.1), then the -CLIENT_MAC, SERVER_MAC, CLIENT_WRITE, and SERVER_WRITE keys are -rederived using the MASTER_KEY from the old session, as well as the -CONNECTION_ID and CH_CHALLENGE values from the SERVER_HELLO and -CLIENT_HELLO messages, respectively, for this connection. (2) If the -SH_EXCH_SPECS_DATA refers to a TOKEN type, then the keys from the -ongoing session continue to be used. In order to obtain fresh key -material or reset the sequence number, TOKEN implementations must use -the redo handshake mechanism (KM_REDO_HANDSHAKE key management -message), or else not request (or not accept) reconnections of an -established session. When this mechanism is used with a TOKEN -exchange type, the client must set the CH_REQUEST_RECONNECT flag to -one and send PCT_SESSION_ID_NONE in the CH_SESSION_ID_DATA field of -the subsequent CLIENT_HELLO message. (See section 4.4.4.) - -In the case of a reconnection, all the remaining data fields are -empty except for SH_RESPONSE_DATA, whose contents are described in -section 7.2. Also, all of the flags in SH_AUTH_OPTIONS are set to -zero except SH_ACCEPT_RECONNECT and possibly SH_ACCEPT_CLOSURE_MON -and/or SH_ACCEPT_REDO_ENABLE. - -If the server does not recognize the session identifier provided by -the client (or if the CH_REQUEST_RECONNECT flag was set to zero), -then the server sets the SH_ACCEPT_RECONNECT flag to zero in the -SH_AUTH_OPTIONS field. A unique session identifier (which must not -equal PCT_SESSION_ID_NONE) is also placed in the SH_SESSION_ID_DATA -field; this value need not be cryptographically random, but values -should not be used repeatedly (a continually increasing counter, for -instance, would be sufficient). The server then selects any choice -with which it is compatible, from each of the CH_CIPHER_LIST, -CH_HASH_LIST and CH_EXCH_LIST lists supplied in the CLIENT_HELLO -message. (These values are returned to the client in the -SH_CIPHER_SPECS_DATA, SH_HASH_SPECS_DATA and SH_EXCH_SPECS_DATA -fields, respectively.) If no cipher type (respectively, hash type, -key exchange type) from the CH_CIPHER_LIST (respectively, -CH_HASH_LIST, CH_EXCH_LIST) is acceptable to the server, then a -SPECS_MISMATCH error occurs. - -Alternate cipher and hash types from CH_CIPHER_LIST and CH_HASH_LIST, -respectively, with which the server is compatible may be placed in the -SH_ALT_CIPHER_LIST and SH_ALT_HASH_LIST lists (whose formats are -identical to those of CH_CIPHER_LIST and CH_HASH_LIST, respectively); -these lists can then be used by the client in determining whether -pre-encrypted, pre-MAC'd data will be understandable to the server. -(Filling these lists is optional for the server; an empty list simply -means that the client has no assurance that the server supports any -cipher or hash type other than the one selected for the session.) -Finally, the SH_MSG_LIST list contains a list of those data message -types from CH_MSG_LIST which the server also supports; the format of -the two message type lists is identical. - -The server also examines the CH_AUTH_OPTIONS flags to select server -authentication and key exchange options acceptable to both (as -indicated by the CH_AUTH_OPTIONS flags and the server's own -requirements/compatibilities), and to offer a set of acceptable -client authentication options. In particular, these must include a -server authentication type if any of the CH_DEMAND_AUTH flags is set -to one, at least one client authentication type if client -authentication is required by the server, and a key exchange -direction (or two) acceptable to both client and server, as indicated -by the CH_DEMAND_KEY_EXCH_SEND and CH_OFFER_KEY_EXCH_RECEIVE flags -and the server's own requirements. (The restrictions on -password-based authentication must also be obeyed; see section 5.1.2.) -If no such set of types is available that is acceptable to both client -and server, then a SPECS_MISMATCH error occurs. If at least one such -set of types is found, then the server sets the associated flags in -SH_AUTH_OPTIONS (at most one SH_ACCEDE_AUTH flag and at least one -SH_ACCEDE/ACCEPT_KEY_EXCH flag); these determine the type of server -authentication to be performed, if any, and the direction of the key -exchange(s), as well as the set of client authentication options -acceptable to the server. The type of the key exchange(s) (they must -both be of the same type, if there are two) is selected by the server, -and indicated by the code in the SH_EXCH_SPECS field. - -If the server requires client authentication, then the server also -selects those choices from the CH_SIG_LIST, CH_CERT_LIST and -CH_CERTIFIER_LIST lists that are also acceptable -CH_OFFER_CERTIFIER_TRYOUT is set to one). These server-selected -lists are placed in the SH_SIG_LIST_DATA, SH_CERT_LIST_DATA and -SH_CERTIFIER_LIST_DATA fields, respectively; their format is -identical to those of the corresponding fields in the CLIENT_HELLO -message. If the server does not require client authentication, then -the SH_SIG_LIST, SH_CERT_LIST and SH_CERTIFIER_LIST fields are -empty, and their length is zero. The server may also, like the -client, demand certificate-based authentication but set the -SH_OFFER_CERTIFIER_TRYOUT flag to one. In this case, the server -simply reserves the right to reject certificates from unacceptable -certifiers, and its list of acceptable ones is not assumed -exhaustive. - -If the SH_ACCEDE_KEY_EXCH_RECEIVE flag is set to one and the -CH_QUICK_SERVER_CERT field is either empty or contains an -incorrect public value, then the SH_PUBLIC_VALUE_DATA field contains -a (possibly certified) key-exchange public key of a type compatible -with the chosen key exchange type specified in the -SH_EXCH_SPECS_DATA field. If, moreover, the -SH_ACCEDE_AUTH_KEY_EXCH flag is set to one, then the key-exchange -public key is contained in a certificate whose type and certifier -are found in the CH_CERT_LIST and CH_CERTIFIER_LIST lists, -respectively (if CH_CERTIFIER_LIST is non-empty). Otherwise, the -public key is uncertified. The format of the SH_PUBLIC_VALUE_DATA -field is described in section 6.1.2. If the -SH_ACCEDE_KEY_EXCH_RECEIVE flag is set to zero, then the -SH_PUBLIC_VALUE_DATA field is empty, and its length is zero. - -If the client sent an acceptable key-exchange public key certificate -in the CH_QUICK_PUBLIC_VALUE field of the CLIENT_HELLO message, then -the server responds with an RSA-encrypted master key (or randomly -chosen Diffie-Hellman/FORTEZZA KEA public value) in the -SH_QUICK_ENCRYPTED_KEY field of the SERVER_HELLO message. (The -format of this field is described in section 6.1.2.) - -If the client sent an acceptable certified server key-exchange -public key and encrypted master key in the CH_QUICK_SERVER_CERT and -CH_QUICK_ENCRYPTED_KEY fields of the CLIENT_HELLO message, and if the -SH_ACCEPT_KEY_EXCH_SEND flag in the SH_AUTH_OPTIONS field is set to -zero, then the key exchange is completed, and the server must place an -authentication response, constructed as described in section 7.2, in -SH_RESPONSE_DATA if one of the CH_DEMAND_AUTH flags is set to one. If -the SH_ACCEDE_AUTH_SIG flag is set to one, then the SH_SIG_CERT_DATA -field contains a certified digital signature public key acceptable to -the client (as indicated by the CH_SIG_LIST, CH_CERT_LIST and -CH_CERTIFIER_LIST lists), in the format of a PUBLIC_VALUE field of -type PV_CERTIFICATE (see section 6.1.2). If the -SH_ACCEDE_AUTH_PASSWORD flag is set to one, then an identity indicator -(such as an account identifier or, in the case of doubly certified -Diffie-Hellman key exchange, a certificate for the Diffie-Hellman -public value supplied by the server in the key exchange) is placed in -the SH_SIG_CERT_DATA field. Otherwise the SH_SIG_CERT_DATA field is -empty, and its length is zero. - -When the client receives a SERVER_HELLO message, it checks whether the -server has accepted a reconnection of an old session or is -establishing a new session. If the session is an old one, then the -client establishes the new CLIENT_WRITE_KEY, SERVER_WRITE_KEY, -CLIENT_MAC_KEY and SERVER_MAC_KEY according to the cipher-specific -rules described in section 6.1.4. The client then checks the -contents of the RESPONSE_DATA field in the SERVER_HELLO message for -correctness. If the response exactly matches the value calculated by -the client (following the procedures in sections 7.1 and 7.2), then -the handshake is finished, and the client proceeds to the -CLIENT_MASTER_KEY messsage, if necessary, or else begins sending -data; otherwise, a SERVER_AUTH_FAILED error occurs. - -If a new session is being initiated, the client records the chosen -cipher, hash, key exchange and signature types, and the lists of -alternate cipher and hash types and supported data message types. -If certificate-based client authentication is required the client -checks the list of certificate types and certifiers to see if it has -a satisfactory certificate; lack of one results in a SPECS_MISMATCH -error. If an acceptable quick encrypted master key was sent, the -client decrypts the master key for use in obtaining a MAC_KEY and -WRITE_KEY for each transmission direction as described in section -6.1.4. Finally, if a non-empty RESPONSE_DATA field was included, then -the client checks it for correctness. If it exactly matches the -value calculated by the client (following the procedures in sections -7.1 and 7.2), then the client proceeds to the CLIENT_MASTER_KEY -handshake message (or, if the handshake is completed, begins sending -data); otherwise, a SERVER_AUTH_FAILED error occurs. - - -5.2.3 CLIENT_MASTER_KEY - -char CMK_ENCRYPTED_KEY_LENGTH[2] -char CMK_RESPONSE_LENGTH[2] -char CMK_SIG_CERT_LENGTH[4] -char CMK_PUBLIC_VALUE_LENGTH[4] -char CMK_ENCRYPTED_KEY_DATA[([0] << 8)|[1]] -char CMK_RESPONSE_DATA[([0] << 8)|[1]] -char CMK_SIG_CERT_DATA[([0] << 24)|([1] << 16)|([2] << 8)|[3]] -char CMK_PUBLIC_VALUE_DATA[([0] << 24)|([1] << 16)|([2] << 8)|[3]] - -The client sends this message after receiving the SERVER_HELLO message -from the server if not all the key exchanges and authentications (as -indicated by the SH_AUTH_OPTIONS field) have yet been completed. - -If SH_ACCEPT_AUTH_SIG is set to one, and no other client -authentication option is both acceptable to the server and preferred -by the client, then CMK_SIG_CERT_DATA contains a certified digital -signature public key acceptable to the server (as indicated by the -(SH_CERT_LIST, SH_CERTIFIER_LIST and SH_SIG_LIST lists), in the form -of a PUBLIC_VALUE field of type PV_CERTIFICATE (see section 6.1.2). -If SH_ACCEPT_AUTH_PASSWORD is set to one, then CMK_SIG_CERT_DATA -contains an identity indicator (such as an account identifier, or, in -the case of doubly certified Diffie-Hellman key exchange, a -certificate for the Diffie-Hellman public value supplied by the -server in the key exchange). Otherwise the CMK_SIG_CERT_DATA field -is empty, and its length is zero. - -If SH_ACCEPT_KEY_EXCH_SEND is set to one, and an acceptable -encrypted master key has not already been sent in the -SH_QUICK_ENCRYPTED_KEY field of the SERVER_HELLO message, then -CMK_PUBLIC_VALUE_DATA contains an RSA key exchange public key or -Diffie-Hellman/FORTEZZA KEA public value. If -SH_ACCEPT_AUTH_KEY_EXCH is set to one, and no other client -authentication option is both acceptable to the server and preferred -by the client, then this public value is contained in a certificate -acceptable to the server (as indicated by the SH_EXCH_SPECS_DATA -field and the SH_CERT_LIST and SH_CERTIFIER_LIST lists); otherwise, -the value is uncertified. If the SH_ACCEPT_KEY_EXCH_SEND flag is set -to zero, or if an acceptable encrypted master key was sent in the -SERVER_HELLO message, then CMK_PUBLIC_VALUE_DATA is empty. - -If SH_ACCEDE_KEY_EXCH_RECEIVE is set to one, and if -SH_PUBLIC_VALUE_DATA was not empty (indicating that the contents of -the CH_QUICK_ENCRYPTED_KEY field in the CLIENT_HELLO message were -either absent or not acceptable), then CMK_ENCRYPTED_KEY contains an -RSA-encrypted master key (or randomly chosen Diffie-Hellman/FORTEZZA -KEA public value); see section 6.1.2. If SH_ACCEDE_KEY_EXCH_RECEIVE -is set to one, or if SH_PUBLIC_VALUE_DATA is empty, then -CMK_ENCRYPTED_KEY is empty, with length zero. - -If all key exchanges are completed by the sending of the -CLIENT_MASTER_KEY message, and if one of the SH_ACCEPT_AUTH flags is -set to one, then the contents of the CMK_RESPONSE field are as -described in section 7.2; otherwise, this field is empty, and its -length is zero. - -Upon receiving a CLIENT_MASTER_KEY message, the server verifies the -certificates and/or authentication response, if they are required; -errors in any of these result in a BAD_CERTIFICATE or -CLIENT_AUTH_FAILED error, respectively. If an encrypted master key -was sent, the server decrypts the master key for use in obtaining a -MAC_KEY and WRITE_KEY for each transmission direction as described in -section 6.1.4. The server then proceeds to the SERVER_VERIFY -message, if necessary, or else begins transmitting data. - - -5.2.4 SERVER_VERIFY - -char SV_ENCRYPTED_KEY_LENGTH[2] -char SV_RESPONSE_LENGTH[2] -char SV_SIG_CERT_LENGTH[4] -char SV_ENCRYPTED_KEY_DATA[([0] << 8)|[1]] -char SV_RESPONSE_DATA[([0] << 8)|[1]] -char SV_SIG_CERT_DATA[([0] << 24)|([1] << 16)|([2] << 8)|[3]] - -The server sends this message upon receiving a valid CLIENT_MASTER_KEY -message from the client, if not all key exchanges and authentications -have been completed. - -If SH_SIG_CERT_DATA was empty, and either SH_ACCEDE_AUTH_SIG or -SH_ACCEDE_AUTH_PASSWORD is set to one, then the SV_SIG_CERT_DATA -field must not be empty. If SH_ACCEDE_AUTH_SIG is set to one, -then SV_SIG_CERT_DATA must contains a certified digital signature -public key acceptable to the client (as indicated by the -(CH_SIG_LIST, CH_CERT_LIST and CH_CERTIFIER_LIST lists), in the form -of a PUBLIC_VALUE field of type PV_CERTIFICATE (see section 6.1.2). -If SH_ACCEPT_AUTH_PASSWORD is set to one, then SV_SIG_CERT_DATA -contains an identity indicator (such as an account identifier, or, in -the case of doubly certified Diffie-Hellman key exchange, a -certificate for the Diffie-Hellman public value supplied by the -server in the key exchange). Otherwise the SV_SIG_CERT_DATA field is -empty, and its length is zero. - -If SH_ACCEPT_KEY_EXCH_SEND is set to one, and if -CMK_PUBLIC_VALUE_DATA was not empty (indicating that the contents of -the SH_QUICK_ENCRYPTED_KEY field in the SERVER_HELLO message were -either absent or not acceptable), then SV_ENCRYPTED_KEY contains an -RSA-encrypted master key (or randomly chosen Diffie-Hellman/FORTEZZA -KEA public value). The format of this field is described in section -6.1.2. If SH_ACCEPT_KEY_EXCH_SEND is set to one, or if -CMK_PUBLIC_VALUE is empty, then SV_ENCRYPTED_KEY is empty, with -length zero. - -If one of the SH_ACCEPT_AUTH flags is set to one, then the contents -of the SV_RESPONSE field are as described in section 7.2; otherwise, -this field is empty, and its length is zero. - -Upon receiving the SERVER_VERIFY message, the client verifies the -certificates and/or authentication response, if they are required; -errors in any of these result in a BAD_CERTIFICATE or -SERVER_AUTH_FAILED error, respectively. If an encrypted master key -was sent, the client decrypts the master key for use in obtaining a -MAC_KEY and WRITE_KEY for each transmission direction as described -in section 6.1.4. The client then proceeds to the CLIENT_VERIFY -message, if necessary, or else begins transmitting data. - - -5.2.5 CLIENT_VERIFY - -char CV_RESPONSE_LENGTH[2] -char CV_SIG_CERT_LENGTH[4] -char CV_RESPONSE_DATA[([0] << 8)|[1]] -char CV_SIG_CERT_DATA[([0] << 24)|([1] << 16)|([2] << 8)|[3]] - -The client sends this message upon receiving a valid SERVER_VERIFY -message from the client, if client authentication has not been -completed. This message is never necessary unless -SH_ACCEPT_KEY_EXCH_SEND was set to one. - -If either SH_ACCEDE_AUTH_SIG or SH_ACCEDE_AUTH_PASSWORD is set to one, -then the CV_SIG_CERT_DATA field must not be empty. If -SH_ACCEDE_AUTH_SIG is set to one, then CV_SIG_CERT_DATA must contain -a certified digital signature public key acceptable to the server (as -indicated by the (SH_SIG_LIST, SH_CERT_LIST and SH_CERTIFIER_LIST -lists), in the form of a PUBLIC_VALUE field of type PV_CERTIFICATE -(see section 6.1.2). If SH_ACCEPT_AUTH_PASSWORD is set to one, then -CV_SIG_CERT_DATA contains an identity indicator (such as an account -identifier, or, in the case of doubly certified Diffie-Hellman key -exchange, a certificate for the Diffie-Hellman public value supplied -by the server in the key exchange). Otherwise the CV_SIG_CERT_DATA -field is empty, and its length is zero. The contents of the -CV_RESPONSE field are as described in section 7.2. - -Upon receiving the CLIENT_VERIFY message, the server verifies the -certificate, if required, and the authentication response; errors in -either of these result in a BAD_CERTIFICATE or CLIENT_AUTH_FAILED -error, respectively. The server may then begin transmitting data. - - -6. Algorithm and Certificate Types - -6.1 Key exchange algorithms - -6.1.1 Key exchange algorithm types - -PCT version 2 permits the following key exchange types: - -PCT_EXCH_RSA_PKCS1 -PCT_EXCH_RSA_PKCS1_TOKEN_DES -PCT_EXCH_RSA_PKCS1_TOKEN_DES3 -PCT_EXCH_RSA_PKCS1_TOKEN_RC2 -PCT_EXCH_RSA_PKCS1_TOKEN_RC4 -PCT_EXCH_DH_PKCS3 -PCT_EXCH_DH_PKCS3_TOKEN_DES -PCT_EXCH_DH_PKCS3_TOKEN_DES3 -PCT_EXCH_FORTEZZA_TOKEN - -Note that the token-based key exchange types (those types whose -labels contain the word TOKEN) specify cipher as well (including, -implicitly, the FORTEZZA KEA key exchange type); if one of these is -chosen, then its choice of cipher overrides whatever choice of -cipher appears in the SH_CIPHER_SPECS_DATA field of the SERVER_HELLO -message. - -These key exchanges may use the (QUICK_)PUBLIC_VALUE field in any -handshake message, as well as the (QUICK_)ENCRYPTED_KEY field in the -subsequent handshake message. The (first) public value sent is said -to be sent by (or previously obtained from) the "receiver", and the -second value by the "sender". If the sender is the client, then the -key exchange is said to be "server-directed"; if the sender is the -server, then it is said to be "client-directed". - - -6.1.2 Key exchange field formats - -The format of the (QUICK_)PUBLIC_VALUE field in any handshake -message in which it appears is as follows: - -char PV_PUBLIC_VALUE_TYPE[2] -char PV_USER_INFO_LENGTH[4] -char PV_PARAMETER_1_LENGTH[2] -char PV_PARAMETER_2_LENGTH[2] -char PV_USER_INFO_DATA[([0] << 24)|([1] << 16)|([2] << 8)|[3]] -char PV_PARAMETER_1_DATA[([0] << 8)|[1]] -char PV_PARAMETER_2_DATA[([0] << 8)|[1]] - -There are five permissible values for PUBLIC_VALUE_TYPE. If -PV_TYPE_CERTIFICATE is specified, then a certificate of a type -acceptable to the key exchange sender (as indicated by the -CH_CERT_LIST in the CLIENT_HELLO message, or the SH_CERT_LIST list, -in the SERVER_HELLO message, as appropriate) appears in the -PV_USER_INFO field, and both PV_PARAMETER fields are empty, with -length zero. (The PV_PARAMETER_1_LENGTH field contains the -two-byte certificate type code identifying the type of the -certificate sent; this field is not, however, interpreted as the -length of the PV_PARAMETER_1_LENGTH field, which is still empty; -see section 6.4.) If PV_TYPE_PKCS_TOKEN is specified, then the -PV_USER_INFO field contains a PKCS-format public key of the type -(RSA or Diffie-Hellman) indicated by the SH_EXCH_SPECS field in the -SERVER_HELLO message. If PV_TYPE_KEA is specified, then the -PV_USER_INFO field contains a KEA public value exactly as generated -by the FORTEZZA token, and both PV_PARAMETER fields are empty, with -length zero. If PV_TYPE_EPHEMERAL_RSA is specified, then -PV_USER_INFO contains the RSA modulus from the RSA public value -being sent; PV_PARAMETER_1 contains the associated RSA exponent; and -PV_PARAMETER_2 is empty, with length zero. If PV_TYPE_EPHEMERAL_DH -is specified, then PV_USER_INFO contains the actual Diffie-Hellman -public value; PV_PARAMETER_1 contains the generator used to -construct it; and PV_PARAMETER_2 contains the prime modulus used to -construct it. For both EPHEMERAL public value types, the values in -all fields are represented with the most significant byte first, and -in descending order, with the least significant byte last. - -The (QUICK_)ENCRYPTED_KEY_DATA field in any handshake message in -which it appears has the following format: - -char EK_ENCRYPTED_KEY_1_LENGTH[2] -char EK_ENCRYPTED_KEY_2_LENGTH[2] -char EK_ENCRYPTED_KEY_3_LENGTH[2] -char EK_KEY_ARG_LENGTH[2] -char EK_ENCRYPTED_KEY_1_DATA[([0] << 8)|[1]] -char EK_ENCRYPTED_KEY_2_DATA[([0] << 8)|[1]] -char EK_ENCRYPTED_KEY_3_DATA[([0] << 8)|[1]] -char EK_KEY_ARG_DATA[([0] << 8)|[1]] - -Details of the use of these subfields is described below. - - -6.1.3 Master key exchange - -For the PCT_EXCH_RSA_PKCS1 key exchange type, a MASTER_KEY value is -generated by the sender, which should be random in the following -strong sense: attackers must not be able to predict any of the bits in -the MASTER_KEY. It is recommended that the bits used be either truly -random and uniformly generated (using some random physical process) or -else generated using a cryptographically secure pseudorandom number -generator, which was in turn seeded with a truly random and uniformly -generated seed. This MASTER_KEY value is encrypted using the -receiver's (possibly certified) public encryption key, as obtained -from the (QUICK_)PUBLIC_VALUE_DATA field of some handshake message -(or possibly some time earlier, if the key is certified). The -encryption must follow the RSA PKCS#1 standard format (see [3]), -block type 2. This encryption is sent to the server in the -EK_ENCRYPTED_KEY_1_DATA subfield in the (QUICK_)ENCRYPTED_KEY_DATA -field of the handshake message following the one containing the public -value used (or the sender's first handshake message, if the public -key was obtained at an earlier time). The encrypted key is decrypted -by the receiver to obtain the MASTER_KEY. If two key exchanges of -this type are performed (one in each direction), then the MASTER_KEY -value is simply the concatenation of the two values, in the order in -which they were sent. Use of the ENCRYPTED_KEY_2_DATA subfield is -described in section 6.1.5; the ENCRYPTED_KEY_3_DATA subfield is left -empty, with length zero. - -For the PCT_EXCH_DH_PKCS3 key exchange type, a random private value x -(generated in the same way as the MASTER_KEY above) and corresponding -public value y are generated by the sender following RSA PKCS#3 -standard format (see [4]). The value y is then sent to the receiver -in the EK_ENCRYPTED_KEY_1_DATA subfield of the -(QUICK_)ENCRYPTED_KEY_DATA field of some handshake message. The -sender's private value x, along with the (possibly certified) public -value y' included in the (QUICK_)PUBLIC_VALUE_DATA field of the -previous handshake message (or possibly obtained earlier), is used to -generate the MASTER_KEY. The receiver uses its private value, x', -along with the y value sent by the sender, to obtain the same -MASTER_KEY value. If two key exchanges of this type are performed -(one in each direction), then the MASTER_KEY is simply the -concatenation of the two values, in the order in which they were sent. -Use of the ENCRYPTED_KEY_2_DATA subfield is described in section -6.1.5; the ENCRYPTED_KEY_3_DATA subfield is left empty, with length -zero. - -For the various TOKEN key exchange types, an encrypted -CLIENT_WRITE_KEY is contained in the ENCRYPTED_KEY_1_DATA subfield, -and an encrypted SERVER_WRITE_KEY is contained in the -ENCRYPTED_KEY_2_DATA subfield of the (QUICK_)ENCRYPTED_KEY field. -The format of the data is defined by the token implementation. For -example, in the case of FORTEZZA tokens, the ENCRYPTED_KEY_1_DATA -subfield (like the (QUICK_)PUBLIC_VALUE field sent before it, or -obtained earlier), contains a KEA public value generated by the token -for key exchange. The result is a CLIENT_WRITE_KEY shared by sender -and receiver, which is used, along with the initialization vector in -the accompanying EK_KEY_ARG_DATA field, if needed (see section -6.1.5), to encrypt the SERVER_WRITE_KEY sent in the -ENCRYPTED_KEY_2_DATA subfield. In all token types, this shared -encryption key is used to encrypt a 128-bit MASTER_KEY value for -MAC_KEY derivation (as described below). This MASTER_KEY is sent in -the EK_ENCYRYPTED_KEY_3_DATA field of the ENCRYPTED_KEY_DATA subfield -accompanying the encryption key material, and uses the initialization -vector in the accompanying EK_KEY_ARG_DATA field, if needed (see -section 6.1.5). - -The length of the MASTER_KEY depends on the key exchange type, and on -how many key exchanges were performed. It is 128 bits if one RSA -key exchange was performed, and 256 bits if two exchanges were -performed and the results concatenated. For Diffie-Hellman key -exchange, it is the length of the receiver's public value if one key -exchange was performed, and the sum of the lengths of each receiver's -public value if two key exchanges were performed. For token-based -key exchange types, the MASTER_KEY (which is only relevant for MAC -derivation) is 128 bits long. - - -6.1.4 Key derivation - -The CLIENT_WRITE_KEY_SEED and SERVER_WRITE_KEY_SEED are used (for -non-token key exchange types) to compute the CLIENT_WRITE_KEY and -SERVER_WRITE_KEY, respectively. They are computed as follows: - -CLIENT_WRITE_KEY_SEED_i = Hash( i, "cw", MASTER_KEY, "cw"^i, -SH_CONNECTION_ID_DATA, "cw"^i, SH_SESSION_ID_DATA,"cw"^i, -CH_CHALLENGE_DATA, "cw"^i ) - -SERVER_WRITE_KEY_SEED_i = Hash( i, "svw", MASTER_KEY, "svw"^i, -SH_CONNECTION_ID_DATA, "svw"^i, CH_CHALLENGE_DATA, "svw"^i ) - -The function "Hash" is the one determined by the value of -SH_HASH_SPECS_DATA (see section 5.2.2). The value of i ranges from -1 to m, where m is the negotiated encryption key length (the value in -the third byte of the SH_CIPHER_SPECS_DATA field) divided by the hash -output length, in bits, rounded up to the nearest integer. This -resulting string is then truncated if necessary to produce a string -of the correct length. - -When a token key exchange type is used, no WRITE_KEY_SEED values are -computed, and the client and server WRITE_KEY values are defined by -the specific key exchange method for the token. For example, the -encryption keys exchanged in the KEA key exchange process described -in section 6.1.3 become the CLIENT_WRITE_KEY and SERVER_WRITE_KEY for -the session. - -The CLIENT_MAC_KEY_SEED and SERVER_MAC_KEY_SEED are always computed -as follows: - -CLIENT_MAC_KEY_SEED_i = Hash( i, MASTER_KEY, "cmac"^i, -SH_CONNECTION_ID_DATA, "cmac"^i, SH_SESSION_ID_DATA, "cmac"^i, -CH_CHALLENGE_DATA, "cmac"^i ) - -SERVER_MAC_KEY_SEED_i = Hash( i, MASTER_KEY, "svmac"^i, -SH_CONNECTION_ID_DATA, "svmac"^i, CH_CHALLENGE_DATA, "svmac"^i ) - -The function "Hash" is the one determined by the value of -SH_HASH_SPECS_DATA (see section 5.2.2). The value of i ranges from -1 through m, where m is the negotiated MAC key length (64 plus the -value in the fourth byte of the SH_CIPHER_SPECS_DATA field) divided -by the hash output length, in bits, rounded up to the nearest integer. -The resulting string is then truncated if necessary to produce a -string (CLIENT_MAC_KEY_SEED or SERVER_MAC_KEY_SEED) of the correct -MAC_KEY length. This string is then padded, by repeatedly appending -the byte PCT_MAC_KEY_PAD_BYTE , until it is the standard key length -for the hash function used in MAC computation (each hash function has -an associated standard MAC key length; see section 6.3). This final -result is the MAC_KEY (CLIENT_MAC_KEY or SERVER_MAC_KEY). - -Note that tokens which are capable of deriving keys using "keyed -hashes", as described above, are free to use the PCT_EXCH_RSA_PKCS1 -or PCT_EXCH_DH_PKCS3 key exchange type to exchange the MASTER_KEY, -and then to derive the rest of the keys normally. The TOKEN key -exchange types are for tokens that cannot do such keyed-hash key -derivation, and can only use an exchanged key for bulk encryption -(of, for example, the MASTER_KEY value used for MAC_KEY derivation). -Such tokens can exchange multiple keys by using an initially -exchanged encryption key to encrypt other keys, as described above. - -Key derivation for datagram records is somewhat different from normal -key derivation. In a datagram record, the necessary key information -is contained in the DG_ENCRYPTED_KEY field at the beginning of a -datagram record. Its ENCRYPTED_KEY_1_DATA subfield contains a -16-byte random value, which should be cryptographically random in the -same sense as the MASTER_KEY (see section 6.1.3). This value is used -to generate the new WRITE_KEY (in the case of non-token key exchange -types) and the MAC_KEY for the datagram. These are generated by -computing a temporary MASTER_KEY as follows: - -TEMP_MASTER_KEY_i = Hash( i, MASTER_KEY, "tmk"^i, -ENCRYPTED_KEY_1_DATA ) - -The function "Hash" is the one determined by the value of -SH_HASH_SPECS_DATA in the most recent SERVER_HELLO handshake message -for this connection (see section 5.2.2). The value of i ranges from -1 through m, where m is 128 divided by the hash output length, in -bits, rounded up to the nearest integer. The resulting concatenated -string is then truncated if necessary to produce a 128-bit string. -The new WRITE_KEYs (in the case of non-token key exchange types) and -new MAC_KEYs are then computed normally, except that MASTER_KEY is -replaced with TEMP_MASTER_KEY. - -If the current keys were generated using a token-type key exchange, -then the DG_ENCRYPTED_KEY_2_DATA subfield contains the key information -necessary to decrypt the datagram, encrypted in a manner that the -token can decrypt. (Note that the token type must support this type -of context-independent encryption of keys; otherwise, this type of key -management message is not permitted.) For example, when FORTEZZA -tokens are used, the DG_ENCRYPTED_KEY_2_DATA subfield contains the -WRITE_KEY encrypted, as a key, using the current WRITE_KEY. - -The DG_KEY_ARG_DATA subfield contains an arbitrary initialization -vector, whose use is also explained in section 6.1.5, if a block -cipher is being used; otherwise, the field is empty, and its length is -zero. - -6.1.5 Key expansion and cipher use - -Every cipher has an associated standard key length (see section 6.2). -When a non-token key exchange type has been used, and encryption keys -of standard length for the specified cipher have been specified in -the SH_CIPHER_SPECS field, then the values of CLIENT_WRITE_KEY and -SERVER_WRITE_KEY are simply CLIENT_WRITE_KEY_SEED and -SERVER_WRITE_KEY_SEED, respectively, and the ENCRYPTED_KEY_2_DATA -subfield accompanying the encrypted master key(s) is empty. -Otherwise, the EK_ENCRYPTED_KEY_2_DATA subfield(s) accompanying the -encrypted master key(s) in the key exchange(s) contain(s) random -"salt" for encryption key derivation. (The salt should be -cryptographically random in the same sense as the MASTER_KEY; see -section 6.1.3.) If only one key exchange occurred, then the salt data -used (which we will call CLEAR_KEY_DATA) is just the value in the -ENCRYPTED_KEY_2_DATA subfield accompanying the encrypted master key; -if two key exchanges are used, then both EK_ENCRYPTED_KEY_2_DATA -fields accompanying the encrypted master keys contain this random -data, and CLEAR_KEY_DATA is their concatenation, in the order in which -they were sent. When a key length is specified which is less than the -standard key length for the specified cipher, then keys of the -specified length are derived normally as described in section 6.1.4, -and then "expanded" to derive standard-length keys. The expansion -proceeds as follows: - -1. Assign to d the result of dividing the standard key length for -the cipher, in bits, by the output length of the hash function, in -bits, rounded up to the nearest integer. - -2. Divide CLEAR_KEY_DATA sequentially into d equal subsegments. -(Note that the length of the CLEAR_KEY_DATA field must therefore be a -multiple of d bytes, and that no two of its d equal parts, when so -divided, may be identical.) Denote these subsegments CLEAR_KEY_DATA_1 -through CLEAR_KEY_DATA_d. - -3. Compute the d hash values - -WRITE_KEY_i := Hash( i, "sl"^i, WRITE_KEY_SEED, "sl"^i, -CLEAR_KEY_DATA_i ). - -The function "Hash" is the one determined by the value of -SH_HASH_SPECS_DATA. The WRITE_KEY_SEED is the encryption key seed -value (CLIENT_WRITE_KEY_SEED or SERVER_WRITE_KEY_SEED) being expanded -to standard length. - -4. Concatenate WRITE_KEY_1 through WRITE_LENGTH_KEY_d, and then -truncate as necessary to produce the WRITE_KEY which is actually used -for encryption. - -The EK_KEY_ARG_DATA subfield accompanying the (last) encrypted master -key contains a random eight-byte value to be used as an initialization -vector (IV) for the first encrypted message when a block cipher (any -cipher except RC4) is used. The IV for the first block encrypted in -any subsequent encrypted message is simply the last encrypted block -of the previous message. The EK_KEY_ARG_DATA subfield is empty when -cipher type PCT_CIPHER_RC4 (or key exchange type -PCT_EXCH_RSA_PKCS1_TOKEN_RC4) is used. - -The use of a block cipher also may cause the data length to increase -during encryption, because the ciphertext produced by block ciphers -must always be an integer multiple of the cipher's block size. Hence -when a block cipher is used, the length of the (fully or partially) -encrypted record must be computed from the RH_RECORD_LENGTH value in -the record header. ENCRYPTED_LENGTH, the length of the encrypted -portion of a record, is computed as the smallest multiple of the -cipher's block size that is at least ACTUAL_LENGTH, where -ACTUAL_LENGTH, the length of the encrypted data before encryption, is -computed as RH_RECORD_LENGTH minus the lengths of the unencrypted -portions of the record body (RH_RECORD_LENGTH - MAC_LENGTH - -DG_ENCRYPTED_KEY_LENGTH - 4 in the case of a datagram record, and -RH_RECORD_LENGTH - MAC_LENGTH - 2 in the case of other encrypted record -types). If a block cipher is not used for encryption, then the length -of the encrypted data is unchanged by encryption, and the length of the -record body is therefore simply RH_RECORD_LENGTH. Otherwise, the -length of the entire encrypted record body is ENCRYPTED_LENGTH + -DG_MAC_LENGTH + DG_ENCRYPTED_KEY_LENGTH + 2 in the case of datagram -records, and ENCRYPTED_LENGTH + MAC_LENGTH for other encrypted -record types. - - -6.2 Cipher Types - -PCT version 2 permits the following cipher types to be specified: - -PCT_CIPHER_DES -PCT_CIPHER_IDEA -PCT_CIPHER_RC2 -PCT_CIPHER_RC4 -PCT_CIPHER_DES_112 -PCT_CIPHER_DES_168 - -Each of these types is denoted by a two-byte code, and is followed in -CIPHER_SPECS_DATA fields by two one-byte length specifications, as -described in section 5.2.1. An encryption length specification of -zero associated with any cipher denotes the choice of no encryption; a -key exchange is performed in such cases solely to share keys for MAC -computation. - -PCT_CIPHER_DES denotes DES (see [5]). Its standard key length is 56 -bits. PCT_CIPHER_DES_112 and PCT_CIPHER_DES_168 denote ciphers in -which the input is first encrypted under DES with a first key, then -"decrypted" under DES with a second key, then encrypted under DES with -a third key. For PCT_CIPHER_DES_112, the first and third keys are -identical, and correspond to the initial 56 bits of the 112-bit -WRITE_KEY. The second key corresponds to the final 56 bits of the -WRITE_KEY. For PCT_CIPHER_DES_168, the three keys are distinct, and -correspond to the first, second, and third 56-bit subsegments of the -WRITE_KEY. All three of these DES-based cipher types have 64-bit data -blocks and are used with cipher block chaining (CBC). - -The standard key lengths for PCT_CIPHER_DES_112 and PCT_CIPHER_DES_168 -are 112 bits and 168 bits, respectively. If a key length less than -the standard length is specified for one of these ciphers (or for -PCT_CIPHER_DES), then the WRITE_KEY_SEED is calculated, then expanded -to the standard length as described above. - -Note that before use, each 56-bit DES key must be "adjusted" to add -eight parity bits to form an eight-byte DES key (see [5]). Similarly, -if the specified WRITE_KEY length is less than its corresponding -standard length, then each WRITE_KEY_SEED is expanded to the standard -length using CLEAR_KEY_DATA as described above, to produce one, two, -or three keys of 56 bits each, which are then each "adjusted" by -adding parity bits to form an eight-byte key. - -PCT_CIPHER_IDEA denotes the IDEA block cipher (see [6]), with 64-bit -data blocks and cipher block chaining. This cipher has a standard key -length of 128 bits. - -PCT_CIPHER_RC2 denotes the RC2 block cipher, with 64-bit blocks and -cipher block chaining. Like IDEA, this cipher has a standard key -length of 128 bits. - -PCT_CIPHER_RC4 denotes the RC4 stream cipher. Like the IDEA and RC2 -block ciphers, this cipher has a standard key length of 128 bits. - -6.3 Hash Types - -PCT version 2 permits the following hash function types to be -specified: - -PCT_HASH_MD5 -PCT_HASH_MD5_TRUNC_64 -PCT_HASH_SHA -PCT_HASH_SHA_TRUNC_80 - -The "truncated" hash types (PCT_HASH_MD5_TRUNC_64 and -PCT_HASH_SHA_TRUNC_80) are identical to their non-truncated versions -(PCT_HASH_MD5 and PCT_HASH_SHA, respectively), with the following -exception: when used in the second ("outer") iteration of a MAC -or authentication response, their output is truncated to half its -normal length. (Hence the resulting MAC or authentication response -is also only half the normal length of the hash function's output.) - -PCT_HASH_MD5 denotes the MD5 hash function (see [7]), with 128-bit -output. (Hence PCT_HASH_MD5_TRUNC_64 has 64-bit output in the cases -described above.) PCT_HASH_SHA denotes the Secure Hash Algorithm -(see [8]), with 160-bit output. (Hence PCT_HASH_SHA_TRUNC_80 has -80-bit output in the cases described above.) The standard MAC key length -for all of the above hash functions is 512 bits. - - -6.4 Certificate Types - -PCT version 2 permits the following certificate types to be specified: - -PCT_CERT_X509 -PCT_CERT_PKCS7 -PCT_CERT_PRIVATE - -THese types apply equally to the client's and server's certificates. -PCT_CERT_X509 denotes a CCITT X.509 standard-conformant certificate -(see [10]). PCT_CERT_PKCS7 denotes an RSA PKCS#7 standard-conformant -certificate (see [11]). PCT_CERT_PRIVATE denotes a private format -understood by both the client and server; for instance, it may refer -to an account identifier using which a certificate lookup can be -performed on some agreed-upon certificate database. - - -6.5 Signature Types - -PCT version 2 permits the following signature key types to be -specified: - -PCT_SIG_RSA_MD5 -PCT_SIG_RSA_SHA -PCT_SIG_DSA_SHA - -PCT_SIG_RSA_MD5 denotes the signature scheme consisting of hashing -the data to be signed using the MD5 hash algorithm, and then -performing an RSA private-key signature function (the inverse of RSA -encryption) on the result. The signature must conform to RSA PKCS#1, -block type 1 (see [3]). PCT_SIG_RSA_SHA denotes the same signature -scheme with SHA substituted for MD5. PCT_SIG_DSA_SHA denotes the -signature scheme consisting of hashing the data to be signed using -the SHA hash algorithm, then computing a signature of the resulting -value using the Digital Signature Algorithm (DSA; see [12]). - -7. Response and verification formats - -7.1 Prelude verification - -In order to guard against alteration of handshake messages before the -master key has been exchanged (and MACs therefore made possible), a -"prelude verification" is incorporated into every authentication -response. Basically, the prelude verification is a cryptographic hash -of all handshake messages up to and including the one in which the -first authentication response is included (with the response field -itself omitted). - -Whichever message contains it, the prelude verification value is -computed as: - -VERIFY_PRELUDE_DATA = Hash( "vpd", CLIENT_HELLO, SERVER_HELLO , -CLIENT_MASTER_KEY, SERVER_VERIFY, CLIENT_VERIFY ) ). - -For the purposes of this computation, the handshake messages are -assumed to contain their associated message headers (i.e., their -HS_MSG_TYPE and HS_RECORD_FLAGS fields) and record headers. Also, the -message in which the first non-empty RESPONSE_DATA field is sent is -assumed for this computation not to include its RESPONSE_DATA field -(although its correct length is included), and subsequent messages in -the handshake are assumed to be empty, zero-length values. - -The hash function used is the one specified in SH_HASH_SPECS_DATA. -Note that the client and server need only keep a "running hash" of all -the values passed in each handshake message as they appear, -terminating at the appropriate point to compute the value of -VERIFY_PRELUDE_DATA. - - -7.2 Authentication responses - -The format of an authentication response depends on the type of -authentication required. Because each type of authentication -response may be sent in one of several possible handshake messages -(and by either party), the formats are described separately -here, and apply wherever the authentication response (RESPONSE_DATA) -field is non-empty. - -In the case of key exchange-based authentication, the contents of the -RESPONSE_DATA field are computed as follows: - -RESPONSE_DATA = Hash( MAC_KEY, Hash( "ke", VERIFY_PRELUDE_DATA ) ). - -In the case of digital signature-based authentication, the contents -of the RESPONSE_DATA field are computed as follows: - -RESPONSE_DATA = Signature( VERIFY_PRELUDE_DATA ). - -In the case of private "password"-based authentication, the contents -of the RESPONSE_DATA field are computed as follows: - -RESPONSE_DATA = Hash( MAC_KEY, Hash( "ppw", IDENTITY, PASSWORD, -VERIFY_PRELUDE_DATA ) ). - -Finally, in the case of authentication of a reconnection of a -previously established session, the contents of the RESPONSE_DATA -field are computed as follows: - -RESPONSE_DATA = Hash( MAC_KEY, Hash( "recon", VERIFY_PRELUDE_DATA ) ). - -The computation of the VERIFY_PRELUDE_DATA value is described in -section 7.1. The MAC_KEY is the CLIENT_MAC_KEY if the field is in -the CLIENT_MASTER_KEY or CLIENT_VERIFY message, and SERVER_MAC_KEY if -the field is in the SERVER_HELLO or SERVER_VERIFY message. (The -origin of these MAC keys is described in section 6.1.4.) -The hash function choice used is determined by the -SH_HASH_SPECS_DATA field in this SERVER_HELLO message. - -When a digital signature is used, the signature algorithm is -determined by the type of signature public key found in the -certificate passed in the SIG_CERT_DATA field accompanying the -RESPONSE_DATA field. (Note that the signature algorithm may itself -require that a hash function be applied to the data being signed, -apart from the one used to compute the value in VERIFY_PRELUDE_DATA.) - -When a private password is used, IDENTITY is the identity of the -client or server being authenticated (the contents of the -SIG_CERT_DATA field accompanying the response), and PASSWORD is the -shared private key used in the authentication. (Note that the same -shared password can in principle be used to authenticate either the -client to the server or vice versa, although not both simultaneously.) -In the case of a doubly certified Diffie-Hellman key exchange, the -password is simply the response sender's MAC key generated as a result -of the key exchange; it is considered equivalent to a password because -it does not change from connection to connection or from session to -session. - - -7.3 Message Authentication Codes - -All PCT version 2 records which are encrypted also include a message -authentication code (MAC). This value allows the receiver to verify -that the record containing it has originated with the correct party, -and has not been inserted or tampered with by someone else in -transit. - -The basic PCT MAC is in the form of a keyed hash of the encrypted -data; that is, a MAC function based on a cryptographic hash function -is computed on the encrypted data and the sender's MAC key. (The -derivation of MAC keys is described in section 6.1.) The -cryptographic hash function used is determined by the code contained -in the SH_HASH_SPECS_DATA field in the most recent SERVER_HELLO -message sent during a successful handshake phase this session. A -list of cryptographic hash functions permitted in PCT version 2, and -their associated codes and output lengths, is given in section 6.3. -The MAC is placed in the MAC_DATA field of the record in which it is -found; its length (MAC_LENGTH) is the output length of the hash -function used. - -The MAC value is computed differently for datagram records and for -other records. In datagram records, the MAC is computed as follows: - -DG_MAC_DATA = Hash( MAC_KEY, Hash( RECORD_HEADER_DATA, -DG_ENCRYPTED_KEY_LENGTH, DG_ENCRYPTED_KEY_DATA, DG_ENCRYPTED_DATA ) ) - -If the client is sending the record, then the MAC_KEY is the -CLIENT_MAC_KEY; if the server is sending the record, then the MAC_KEY -is the SERVER_MAC_KEY. (The derivation of these keys is described -in section 6.1.) RECORD_HEADER_DATA contains the four-byte contents -of the datagram record's record header, as described in section 4.2.1. - -For other records containing MACs, the MAC is computed as follows: - -DT_MAC_DATA = Hash( MAC_KEY, Hash( DATA_TYPE, RECORD_HEADER_DATA, -DT_ENCRYPTED_DATA, SEQUENCE_NUMBER ) ) - -If the client is sending the record, then the MAC_KEY is the -CLIENT_MAC_KEY; if the server is sending the record, then the MAC_KEY -is the SERVER_MAC_KEY. (The details of the derivation of these keys -are given in section 6.1.4.) The value of DATA_TYPE is either the -empty string, or the four-byte ASCII string "pecd" if the record -contains pre-encrypted data (see section 4.4.1). RECORD_HEADER_DATA -contains the four-byte contents of the record header described in -section 4.2.1. - -SEQUENCE_NUMBER is the value (represented in network byte order, or -"big endian" order) of a counter which is incremented by both the -sender and the receiver. For each transmission direction, a pair -of counters is kept (one by the sender, one by the receiver). -Before the first (handshake) record is sent or received in a PCT -connection all sequence number counters are initialized to zero -(except in the case of a restarting connection with a token-based -exchange type, in which case the entire cipher state is preserved; -see section 5.2.2). The sender's sender-to-receiver sequence -number is incremented after every record sent, and the receiver's -sender-to-receiver sequence number is incremented after every record -received. (Note that this increment occurs regardless of whether or -not a record is, or has, a continuation record.) Sequence number -counters are 32-bit unsigned quantities, and may not increment past -0xFFFFFFFF. (See section 4.4.4.) - -MACs for pre-encrypted data can be (mostly) precomputed as well. -The inner invocation of the hash function in the computation of -DT_MAC_DATA contains information that will be known at encryption -time, assuming non-datagram transmission and receiver support for -the hash function chosen by the sender for MAC calculation. Hence, -the output of this inner invocation of the hash function can be -stored along with the pre-encrypted data, and the MAC calculated -efficiently at transmission time using the normal MAC_KEY, the -pre-calculated hash value, and the hash function used in the -pre-calculation. A separate sequence number is used for MACs in -pre-encrypted data records until a KM_TYPE_RESUME_KEY message or -another KM_TYPE_FIXED_KEY message is sent and received. This -sequence number begins at zero for the first data record sent and -received after the KM_TYPE_FIXED_KEY message, and is incremented for -each data record sent. Replays of non-pre-encrypted data as -pre-encrypted data are prevented by the DATA_TYPE value "pecd", which -cannot correspond to a record header prefix, in the MAC computation. - -In addition to the special sequence number for pre-encrypted data, -the normal sequence number for the same transmission direction -continues to increment normally as pre-encrypted data messages are -sent and received. This original sequence number is returned to use, -thus incremented, when the next key management message of type -KM_TYPE_RESUME_KEY or KM_TYPE_FIXED_KEY is sent and received. - -The receiver of an encrypted record containing a MAC uses the -appropriate MAC_KEY and the received value of ENCRYPTED_DATA to -compute the correct value of MAC_DATA. The computed MAC_DATA must -agree bit for bit with the transmitted MAC_DATA. If the two are not -identical, then an INTEGRITY_CHECK_FAILED error occurs, and it is -recommended that the record be treated as though it had not been -received. (See section 4.6.) - - -8. Constants - -Following is a list of constant values used in the PCT protocol -version 1. - -8.1 Record and message type codes - -These codes are each placed in the record or message type fields of -PCT records and messages. - -RT_HANDSHAKE := 0x0301 -RT_KEY_MGMT := 0x0302 -RT_DATAGRAM := 0x0303 -RT_ERROR := 0x0304 -RT_USER_DATA := 0x0305 -RT_PCT_VERSION_1_CH := 0x0180 -RT_PCT_VERSION_1_SH := 0x0280 -RT_SSL_VERSION_2_CH := 0x0100 -RT_SSL_VERSION_3_CH := 0x00** -RT_CD_RESERVED := 0x6364 -RT_KR_RESERVED := 0x6B72 -RT_ESCROW := 0x0310 - -HS_CLIENT_HELLO := 0x0000 -HS_SERVER_HELLO := 0x0001 -HS_CLIENT_MASTER_KEY := 0x0002 -HS_SERVER_VERIFY := 0x0003 -HS_CLIENT_VERIFY := 0x0004 - -KM_TYPE_FIXED_KEY := 0x0001 -KM_TYPE_RESUME_KEY := 0x0002 -KM_TYPE_REDO_HANDSHAKE := 0x0003 -KM_TYPE_CLOSE_CONN := 0x0004 - -DM_TYPE_USER_DATA := 0x0000 - -PV_TYPE_CERTIFICATE := 0x0001 -PV_TYPE_PKCS_TOKEN := 0x0002 -PV_TYPE_KEA := 0x0003 -PV_TYPE_EPHEMERAL_RSA := 0x0004 -PV_TYPE_EPHEMERAL_DH := 0x0005 - -EW_TYPE_MASTER_KEY := 0x0001 -EW_TYPE_WRITE_KEYS := 0x0002 - -8.2 Specification Type Codes - -These are codes used to specify types of cipher, key exchange, hash -function, certificate, and digital signature in the protocol. - -PCT_EXCH_RSA_PKCS1 := 0x0001 -PCT_EXCH_RSA_PKCS1_TOKEN_DES := 0x0002 -PCT_EXCH_RSA_PKCS1_TOKEN_DES3 := 0x0003 -PCT_EXCH_RSA_PKCS1_TOKEN_RC2 := 0x0004 -PCT_EXCH_RSA_PKCS1_TOKEN_RC4 := 0x0005 -PCT_EXCH_DH_PKCS3 := 0x0006 -PCT_EXCH_DH_PKCS3_TOKEN_DES := 0x0007 -PCT_EXCH_DH_PKCS3_TOKEN_DES3 := 0x0008 -PCT_EXCH_FORTEZZA_TOKEN := 0x0009 - -PCT_CIPHER_DES := 0x0001 -PCT_CIPHER_IDEA := 0x0002 -PCT_CIPHER_RC2 := 0x0003 -PCT_CIPHER_RC4 := 0x0004 -PCT_CIPHER_DES_112 := 0x0005 -PCT_CIPHER_DES_168 := 0x0006 - -PCT_HASH_MD5 := 0x0001 -PCT_HASH_MD5_TRUNC_64 := 0x0002 -PCT_HASH_SHA := 0x0003 -PCT_HASH_SHA_TRUNC_80 := 0x0004 -PCT_HASH_DES_DM := 0x0005 - -PCT_CERT_NONE := 0x0000 -PCT_CERT_X509 := 0x0001 -PCT_CERT_PKCS7 := 0x0002 -PCT_CERT_PRIVATE := 0x0003 - -PCT_SIG_NONE := 0x0000 -PCT_SIG_RSA_MD5 := 0x0001 -PCT_SIG_RSA_SHA := 0x0002 -PCT_SIG_DSA_SHA := 0x0003 - -8.3 Error Codes - -These codes are used to identify errors, when they occur, in error -messages. - -PCT_ERR_BAD_CERTIFICATE := 0x0001 -PCT_ERR_CLIENT_AUTH_FAILED := 0x0002 -PCT_ERR_ILLEGAL_MESSAGE := 0x0003 -PCT_ERR_INTEGRITY_CHECK_FAILED := 0x0004 -PCT_ERR_SERVER_AUTH_FAILED := 0x0005 -PCT_ERR_SPECS_MISMATCH := 0x0006 -PCT_ERR_CONN_BROKEN := 0x0007 - -8.4 Miscellaneous Codes - -These include PCT version 1 escape type codes, version numbers, -and assorted constants associated with the PCT protocol. - -PCT_VERSION_V2 := 0x0002 - -PCT_SESSION_ID_NONE := 0x00 (32 bytes of zeros) -PCT_MAC_KEY_PAD_BYTE := 0x36 - -PCT_ET_OOB_DATA := 0x01 -PCT_ET_REDO_CONN := 0x02 - -PCT_CH_OFFSET_V1 := 0x000A -PCT_CH_OFFSET_V2 := 0x0018 - -PCT_MAX_RECORD_LENGTH_2_BYTE_HEADER := 32767 -PCT_MAX_RECORD_LENGTH_3_BYTE_HEADER := 16383 -PCT_MAX_RECORD_LENGTH_V2 := 32763 - - -9. PCT version 1 compatibility - -PCT version 1 is a subset of PCT version 2; however, because of -differing formats, connections are identified as either using version -1 or version 2. The identification occurs during the handshake phase; -a value of RT_PCT_VERSION_1_CH in the RH_RECORD_TYPE field of a -record header indicates a PCT version 1 CLIENT_HELLO message, and a -value of RT_PCT_VERSION_1_SH in the RH_RECORD_TYPE field of a -record header indicates a PCT version 1 SERVER_HELLO message. If -the former is the first record received in a connection, it signals -to the receiver that it is expected to be a server in a PCT version -1 connection. The client and server then follow the PCT version 1 -protocol for the remainder of the connection. If the latter is the -response received to a PCT version 2 CLIENT_HELLO message, it signals -to the receiver that it is expected to be a client in a PCT version 1 -type connection. The client and server then follow the PCT version -1 protocol for the remainder of the connection. The PCT version 1 -protocol is specified in [2]. - -Note that a PCT version 1 server implementation that correctly uses -the CH_OFFSET field to determine the location of the data fields in -the CLIENT_HELLO message can successfully interpret a PCT version 2 -CLIENT_HELLO message, and reply with a PCT version 1 SERVER_HELLO -message. However, reconnections in a continued session must maintain -the same version as the first connection for the session. - -Note also that a PCT version 1 record header may have a three-byte -record length field; this format can always be recognized by a first -(most significant) bit of zero in the RH_RECORD_LENGTH field. - - -10. Security Considerations - -This entire document is about security. - - -References - -[1] K. Hickman and T. Elgamal. The SSL Protocol. Internet-draft, -June 1995. - -[2] J. Benaloh, B. Lampson, D. Simon, T. Spies and B. Yee. The -PCT Protocol. Internet Draft, October 1995. - -[3] RSA Laboratories, "PKCS #1: RSA Encryption Standard", Version -1.5, November 1993. - -[4] RSA Laboratories, "PKCS #3: "Diffie-Hellman Key-Agreement -Standard", Version 1.4, November 1993. - -[5] NBS FIPS PUB 46, "Data Encryption Standard", National Bureau of -Standards, US Department of Commerce, Jan. 1977. - -[6] X. Lai, "On the Design and Security of Block Ciphers", ETH Series -in Information Processing, v. 1, Konstanz: Hartung-Gorre Verlag, 1992. - -[7] R. Rivest, RFC 1321: "The MD5 Message Digest Algorithm", April -1992. - -[8] NIST FIPS PUB 180-1, "Secure Hash Standard", National Institute -of Standards and Technology, US Department of Commerce, Apr. 1995. - -[9] ISO/IEC 9797, "Data Cryptographic Techniques--Data Integrity -Mechanism Using a Cryptographic Check Function Employing a Block -Cipher Algorithm", 1989. - -[10] CCITT. Recommendation X.509: "The Directory - Authentication -Framework". 1988. - -[11] RSA Laboratories, "PKCS #7: Cryptographic Message Syntax -Standard", Version 1.5, November 1993. - -[12] NIST FIPS PUB 186, "Digital Signature Standard", National -Institute of Standards and Technology, US Department of Commerce, May -1994. - -[13] B. Schneier, "Applied Cryptography: Protocols, Algorithms, and -Source Code in C", John Wiley & Sons, Inc., 1994. - -[14] R.L. Rivest, A. Shamir, L. Adelman, "A Method for Obtaining -Digital Signatures and Public Key Cryptosystems", MIT Laboratory for -Computer Science and Department of Mathematics, S.L. Graham, -R.L. Rivest ed. Communications of the ACM, February 1978 (Vol 21, -No. 2) pp. 120-126. - -[15] W. Diffie and M.E. Hellman, "New directions in Cryptography", -IEEE Transactions on Information Theory, November 1976 (Vol. IT-22, -No. 6) pp. 644-654. - - -Appendix A: Escrow Support - -To facilitate the escrow of keys used in PCT connections (across -firewalls, for instance), we describe here a protocol which can be -used to encapsulate PCT records, passing the encryption keys for -the connection to a third party. The protocol involves a distinct -escrow record type (RT_ESCROW). An escrow record header has the -normal format, although all flags must always be set to zero. The -record itself has the following format: - -char EW_ESCROW_TYPE[2] -char EW_KEY_ID[16] -char EW_KEY_1_LENGTH[2] -char EW_KEY_2_LENGTH[2] -char EW_KEY_1_DATA[([0] << 8)|[1]] -char EW_KEY_2_DATA[([0] << 8)|[1]] -char EW_ENCLOSED_RECORD_DATA[DATA_LENGTH] - -The two defined escrow record types are EW_TYPE_MASTER_KEY and -EW_TYPE_WRITE_KEYS. In the first type, EW_KEY_1_DATA contains the -MASTER_KEY for this session, and EW_KEY_2_DATA is empty, with length -zero. In the second type, EW_KEY_1_DATA contains the sender's -WRITE_KEY, and EW_KEY_2_DATA contains the non-sender's WRITE_KEY. -These keys are encrypted using a key and format determined by the -EW_KEY_ID field, which contains a 16-byte identifier for the key -used in the encryption. The format of the encryption, and the key -distribution method used, are left to the implementation's discretion. -(For example, a PCT connection between sender and escrower can be used -to exchange a symmetric key and associated identifier; alternatively, -a fixed key-exchange RSA public key can be designated as the escrow -key to be used.) ENCLOSED_RECORD_DATA holds a normal PCT record, -whose length can be calculated from the escrow record's header and the -lengths of the other fields in the escrow record. (Note that the -normal length limit for an escrow record thus imposes a -shorter-than-normal limit on the size of the encapsulated record.) - -In a normal connection, the first record sent after all key exchanges -in the handshake have completed might be encapsulated in an escrow -record; the key(s) so escrowed would be in effect until the next -escrow encapsulation. For example, in a connection between a client -and server each operating "behind" a firewall, the client and server -would each encapsulate their last handshake message (or first data -message) in an escrow record, and pass it to the firewall. Each -firewall would receive the encapsulated record, decrypt the -escrowed key(s), then pass the enclosed record through itself -unaltered. Thereafter, each firewall would be able to read all -messages passing in each direction, until a change of key occurred -(prompted by, say, a key management message, which would presumably -have to be enclosed in another escrow record). - -The type of escrow used depends on the level of trust between client -or server and escrower. If a master key is escrowed, then the -escrower is capable of not only decrypting but also altering messages, -recalculating MACs accordingly. On the other hand, if only the -encryption keys are escrowed, then the escrower is incapable not -only of altering messages, but also of verifying MACs (to determine, -for instance, if the correct encryption key was supplied). -Furthermore, since the shared master key is used to derive independent -keys for datagram messages, escrow of only encryption keys makes -incoming datagram traffic unreadable to the escrower. - - - -Patent Statement - -This version of the PCT protocol relies on the use of patented public -key encryption technology for authentication and encryption. The -Internet Standards Process as defined in RFC 1310 requires a written -statement from the Patent holder that a license will be made -available to applicants under reasonable terms and conditions prior -to approving a specification as a Proposed, Draft or Internet -Standard. - -See existing RFCs, including RFC 1170, that discuss known public key -cryptography patents and licensing terms and conditions. - -The Internet Society, Internet Architecture Board, Internet -Engineering Steering Group and the Corporation for National Research -Initiatives take no position on the validity or scope of the patents -and patent applications, nor on the appropriateness of the terms of -the assurance. The Internet Society and other groups mentioned above -have not made any determination as to any other intellectual property -rights which may apply to the practice of this standard. Any further -consideration of these matters is the user's own responsibility. - -Author's Address - -Daniel R. Simon -Microsoft Corp. -One Microsoft Way -Redmond WA 98052 -USA - -pct@microsoft.com - -This Internet-Draft expires 10 October 1996. - - |