bantou 0.1.0 → 0.2.0

package/.output/server/node_modules/node-forge/lib/tls.js

@@ -0,0 +1,4334 @@
+/**
+ * A Javascript implementation of Transport Layer Security (TLS).
+ *
+ * @author Dave Longley
+ *
+ * Copyright (c) 2009-2014 Digital Bazaar, Inc.
+ *
+ * The TLS Handshake Protocol involves the following steps:
+ *
+ * - Exchange hello messages to agree on algorithms, exchange random values,
+ * and check for session resumption.
+ *
+ * - Exchange the necessary cryptographic parameters to allow the client and
+ * server to agree on a premaster secret.
+ *
+ * - Exchange certificates and cryptographic information to allow the client
+ * and server to authenticate themselves.
+ *
+ * - Generate a master secret from the premaster secret and exchanged random
+ * values.
+ *
+ * - Provide security parameters to the record layer.
+ *
+ * - Allow the client and server to verify that their peer has calculated the
+ * same security parameters and that the handshake occurred without tampering
+ * by an attacker.
+ *
+ * Up to 4 different messages may be sent during a key exchange. The server
+ * certificate, the server key exchange, the client certificate, and the
+ * client key exchange.
+ *
+ * A typical handshake (from the client's perspective).
+ *
+ * 1. Client sends ClientHello.
+ * 2. Client receives ServerHello.
+ * 3. Client receives optional Certificate.
+ * 4. Client receives optional ServerKeyExchange.
+ * 5. Client receives ServerHelloDone.
+ * 6. Client sends optional Certificate.
+ * 7. Client sends ClientKeyExchange.
+ * 8. Client sends optional CertificateVerify.
+ * 9. Client sends ChangeCipherSpec.
+ * 10. Client sends Finished.
+ * 11. Client receives ChangeCipherSpec.
+ * 12. Client receives Finished.
+ * 13. Client sends/receives application data.
+ *
+ * To reuse an existing session:
+ *
+ * 1. Client sends ClientHello with session ID for reuse.
+ * 2. Client receives ServerHello with same session ID if reusing.
+ * 3. Client receives ChangeCipherSpec message if reusing.
+ * 4. Client receives Finished.
+ * 5. Client sends ChangeCipherSpec.
+ * 6. Client sends Finished.
+ *
+ * Note: Client ignores HelloRequest if in the middle of a handshake.
+ *
+ * Record Layer:
+ *
+ * The record layer fragments information blocks into TLSPlaintext records
+ * carrying data in chunks of 2^14 bytes or less. Client message boundaries are
+ * not preserved in the record layer (i.e., multiple client messages of the
+ * same ContentType MAY be coalesced into a single TLSPlaintext record, or a
+ * single message MAY be fragmented across several records).
+ *
+ * struct {
+ *   uint8 major;
+ *   uint8 minor;
+ * } ProtocolVersion;
+ *
+ * struct {
+ *   ContentType type;
+ *   ProtocolVersion version;
+ *   uint16 length;
+ *   opaque fragment[TLSPlaintext.length];
+ * } TLSPlaintext;
+ *
+ * type:
+ *   The higher-level protocol used to process the enclosed fragment.
+ *
+ * version:
+ *   The version of the protocol being employed. TLS Version 1.2 uses version
+ *   {3, 3}. TLS Version 1.0 uses version {3, 1}. Note that a client that
+ *   supports multiple versions of TLS may not know what version will be
+ *   employed before it receives the ServerHello.
+ *
+ * length:
+ *   The length (in bytes) of the following TLSPlaintext.fragment. The length
+ *   MUST NOT exceed 2^14 = 16384 bytes.
+ *
+ * fragment:
+ *   The application data. This data is transparent and treated as an
+ *   independent block to be dealt with by the higher-level protocol specified
+ *   by the type field.
+ *
+ * Implementations MUST NOT send zero-length fragments of Handshake, Alert, or
+ * ChangeCipherSpec content types. Zero-length fragments of Application data
+ * MAY be sent as they are potentially useful as a traffic analysis
+ * countermeasure.
+ *
+ * Note: Data of different TLS record layer content types MAY be interleaved.
+ * Application data is generally of lower precedence for transmission than
+ * other content types. However, records MUST be delivered to the network in
+ * the same order as they are protected by the record layer. Recipients MUST
+ * receive and process interleaved application layer traffic during handshakes
+ * subsequent to the first one on a connection.
+ *
+ * struct {
+ *   ContentType type;       // same as TLSPlaintext.type
+ *   ProtocolVersion version;// same as TLSPlaintext.version
+ *   uint16 length;
+ *   opaque fragment[TLSCompressed.length];
+ * } TLSCompressed;
+ *
+ * length:
+ *   The length (in bytes) of the following TLSCompressed.fragment.
+ *   The length MUST NOT exceed 2^14 + 1024.
+ *
+ * fragment:
+ *   The compressed form of TLSPlaintext.fragment.
+ *
+ * Note: A CompressionMethod.null operation is an identity operation; no fields
+ * are altered. In this implementation, since no compression is supported,
+ * uncompressed records are always the same as compressed records.
+ *
+ * Encryption Information:
+ *
+ * The encryption and MAC functions translate a TLSCompressed structure into a
+ * TLSCiphertext. The decryption functions reverse the process. The MAC of the
+ * record also includes a sequence number so that missing, extra, or repeated
+ * messages are detectable.
+ *
+ * struct {
+ *   ContentType type;
+ *   ProtocolVersion version;
+ *   uint16 length;
+ *   select (SecurityParameters.cipher_type) {
+ *     case stream: GenericStreamCipher;
+ *     case block:  GenericBlockCipher;
+ *     case aead:   GenericAEADCipher;
+ *   } fragment;
+ * } TLSCiphertext;
+ *
+ * type:
+ *   The type field is identical to TLSCompressed.type.
+ *
+ * version:
+ *   The version field is identical to TLSCompressed.version.
+ *
+ * length:
+ *   The length (in bytes) of the following TLSCiphertext.fragment.
+ *   The length MUST NOT exceed 2^14 + 2048.
+ *
+ * fragment:
+ *   The encrypted form of TLSCompressed.fragment, with the MAC.
+ *
+ * Note: Only CBC Block Ciphers are supported by this implementation.
+ *
+ * The TLSCompressed.fragment structures are converted to/from block
+ * TLSCiphertext.fragment structures.
+ *
+ * struct {
+ *   opaque IV[SecurityParameters.record_iv_length];
+ *   block-ciphered struct {
+ *     opaque content[TLSCompressed.length];
+ *     opaque MAC[SecurityParameters.mac_length];
+ *     uint8 padding[GenericBlockCipher.padding_length];
+ *     uint8 padding_length;
+ *   };
+ * } GenericBlockCipher;
+ *
+ * The MAC is generated as described in Section 6.2.3.1.
+ *
+ * IV:
+ *   The Initialization Vector (IV) SHOULD be chosen at random, and MUST be
+ *   unpredictable. Note that in versions of TLS prior to 1.1, there was no
+ *   IV field, and the last ciphertext block of the previous record (the "CBC
+ *   residue") was used as the IV. This was changed to prevent the attacks
+ *   described in [CBCATT]. For block ciphers, the IV length is of length
+ *   SecurityParameters.record_iv_length, which is equal to the
+ *   SecurityParameters.block_size.
+ *
+ * padding:
+ *   Padding that is added to force the length of the plaintext to be an
+ *   integral multiple of the block cipher's block length. The padding MAY be
+ *   any length up to 255 bytes, as long as it results in the
+ *   TLSCiphertext.length being an integral multiple of the block length.
+ *   Lengths longer than necessary might be desirable to frustrate attacks on
+ *   a protocol that are based on analysis of the lengths of exchanged
+ *   messages. Each uint8 in the padding data vector MUST be filled with the
+ *   padding length value. The receiver MUST check this padding and MUST use
+ *   the bad_record_mac alert to indicate padding errors.
+ *
+ * padding_length:
+ *   The padding length MUST be such that the total size of the
+ *   GenericBlockCipher structure is a multiple of the cipher's block length.
+ *   Legal values range from zero to 255, inclusive. This length specifies the
+ *   length of the padding field exclusive of the padding_length field itself.
+ *
+ * The encrypted data length (TLSCiphertext.length) is one more than the sum of
+ * SecurityParameters.block_length, TLSCompressed.length,
+ * SecurityParameters.mac_length, and padding_length.
+ *
+ * Example: If the block length is 8 bytes, the content length
+ * (TLSCompressed.length) is 61 bytes, and the MAC length is 20 bytes, then the
+ * length before padding is 82 bytes (this does not include the IV. Thus, the
+ * padding length modulo 8 must be equal to 6 in order to make the total length
+ * an even multiple of 8 bytes (the block length). The padding length can be
+ * 6, 14, 22, and so on, through 254. If the padding length were the minimum
+ * necessary, 6, the padding would be 6 bytes, each containing the value 6.
+ * Thus, the last 8 octets of the GenericBlockCipher before block encryption
+ * would be xx 06 06 06 06 06 06 06, where xx is the last octet of the MAC.
+ *
+ * Note: With block ciphers in CBC mode (Cipher Block Chaining), it is critical
+ * that the entire plaintext of the record be known before any ciphertext is
+ * transmitted. Otherwise, it is possible for the attacker to mount the attack
+ * described in [CBCATT].
+ *
+ * Implementation note: Canvel et al. [CBCTIME] have demonstrated a timing
+ * attack on CBC padding based on the time required to compute the MAC. In
+ * order to defend against this attack, implementations MUST ensure that
+ * record processing time is essentially the same whether or not the padding
+ * is correct. In general, the best way to do this is to compute the MAC even
+ * if the padding is incorrect, and only then reject the packet. For instance,
+ * if the pad appears to be incorrect, the implementation might assume a
+ * zero-length pad and then compute the MAC. This leaves a small timing
+ * channel, since MAC performance depends, to some extent, on the size of the
+ * data fragment, but it is not believed to be large enough to be exploitable,
+ * due to the large block size of existing MACs and the small size of the
+ * timing signal.
+ */
+var forge = require('./forge');
+require('./asn1');
+require('./hmac');
+require('./md5');
+require('./pem');
+require('./pki');
+require('./random');
+require('./sha1');
+require('./util');
+
+/**
+ * Generates pseudo random bytes by mixing the result of two hash functions,
+ * MD5 and SHA-1.
+ *
+ * prf_TLS1(secret, label, seed) =
+ *   P_MD5(S1, label + seed) XOR P_SHA-1(S2, label + seed);
+ *
+ * Each P_hash function functions as follows:
+ *
+ * P_hash(secret, seed) = HMAC_hash(secret, A(1) + seed) +
+ *                        HMAC_hash(secret, A(2) + seed) +
+ *                        HMAC_hash(secret, A(3) + seed) + ...
+ * A() is defined as:
+ *   A(0) = seed
+ *   A(i) = HMAC_hash(secret, A(i-1))
+ *
+ * The '+' operator denotes concatenation.
+ *
+ * As many iterations A(N) as are needed are performed to generate enough
+ * pseudo random byte output. If an iteration creates more data than is
+ * necessary, then it is truncated.
+ *
+ * Therefore:
+ * A(1) = HMAC_hash(secret, A(0))
+ *      = HMAC_hash(secret, seed)
+ * A(2) = HMAC_hash(secret, A(1))
+ *      = HMAC_hash(secret, HMAC_hash(secret, seed))
+ *
+ * Therefore:
+ * P_hash(secret, seed) =
+ *   HMAC_hash(secret, HMAC_hash(secret, A(0)) + seed) +
+ *   HMAC_hash(secret, HMAC_hash(secret, A(1)) + seed) +
+ *   ...
+ *
+ * Therefore:
+ * P_hash(secret, seed) =
+ *   HMAC_hash(secret, HMAC_hash(secret, seed) + seed) +
+ *   HMAC_hash(secret, HMAC_hash(secret, HMAC_hash(secret, seed)) + seed) +
+ *   ...
+ *
+ * @param secret the secret to use.
+ * @param label the label to use.
+ * @param seed the seed value to use.
+ * @param length the number of bytes to generate.
+ *
+ * @return the pseudo random bytes in a byte buffer.
+ */
+var prf_TLS1 = function(secret, label, seed, length) {
+  var rval = forge.util.createBuffer();
+
+  /* For TLS 1.0, the secret is split in half, into two secrets of equal
+    length. If the secret has an odd length then the last byte of the first
+    half will be the same as the first byte of the second. The length of the
+    two secrets is half of the secret rounded up. */
+  var idx = (secret.length >> 1);
+  var slen = idx + (secret.length & 1);
+  var s1 = secret.substr(0, slen);
+  var s2 = secret.substr(idx, slen);
+  var ai = forge.util.createBuffer();
+  var hmac = forge.hmac.create();
+  seed = label + seed;
+
+  // determine the number of iterations that must be performed to generate
+  // enough output bytes, md5 creates 16 byte hashes, sha1 creates 20
+  var md5itr = Math.ceil(length / 16);
+  var sha1itr = Math.ceil(length / 20);
+
+  // do md5 iterations
+  hmac.start('MD5', s1);
+  var md5bytes = forge.util.createBuffer();
+  ai.putBytes(seed);
+  for(var i = 0; i < md5itr; ++i) {
+    // HMAC_hash(secret, A(i-1))
+    hmac.start(null, null);
+    hmac.update(ai.getBytes());
+    ai.putBuffer(hmac.digest());
+
+    // HMAC_hash(secret, A(i) + seed)
+    hmac.start(null, null);
+    hmac.update(ai.bytes() + seed);
+    md5bytes.putBuffer(hmac.digest());
+  }
+
+  // do sha1 iterations
+  hmac.start('SHA1', s2);
+  var sha1bytes = forge.util.createBuffer();
+  ai.clear();
+  ai.putBytes(seed);
+  for(var i = 0; i < sha1itr; ++i) {
+    // HMAC_hash(secret, A(i-1))
+    hmac.start(null, null);
+    hmac.update(ai.getBytes());
+    ai.putBuffer(hmac.digest());
+
+    // HMAC_hash(secret, A(i) + seed)
+    hmac.start(null, null);
+    hmac.update(ai.bytes() + seed);
+    sha1bytes.putBuffer(hmac.digest());
+  }
+
+  // XOR the md5 bytes with the sha1 bytes
+  rval.putBytes(forge.util.xorBytes(
+    md5bytes.getBytes(), sha1bytes.getBytes(), length));
+
+  return rval;
+};
+
+/**
+ * Generates pseudo random bytes using a SHA256 algorithm. For TLS 1.2.
+ *
+ * @param secret the secret to use.
+ * @param label the label to use.
+ * @param seed the seed value to use.
+ * @param length the number of bytes to generate.
+ *
+ * @return the pseudo random bytes in a byte buffer.
+ */
+var prf_sha256 = function(secret, label, seed, length) {
+   // FIXME: implement me for TLS 1.2
+};
+
+/**
+ * Gets a MAC for a record using the SHA-1 hash algorithm.
+ *
+ * @param key the mac key.
+ * @param state the sequence number (array of two 32-bit integers).
+ * @param record the record.
+ *
+ * @return the sha-1 hash (20 bytes) for the given record.
+ */
+var hmac_sha1 = function(key, seqNum, record) {
+  /* MAC is computed like so:
+  HMAC_hash(
+    key, seqNum +
+      TLSCompressed.type +
+      TLSCompressed.version +
+      TLSCompressed.length +
+      TLSCompressed.fragment)
+  */
+  var hmac = forge.hmac.create();
+  hmac.start('SHA1', key);
+  var b = forge.util.createBuffer();
+  b.putInt32(seqNum[0]);
+  b.putInt32(seqNum[1]);
+  b.putByte(record.type);
+  b.putByte(record.version.major);
+  b.putByte(record.version.minor);
+  b.putInt16(record.length);
+  b.putBytes(record.fragment.bytes());
+  hmac.update(b.getBytes());
+  return hmac.digest().getBytes();
+};
+
+/**
+ * Compresses the TLSPlaintext record into a TLSCompressed record using the
+ * deflate algorithm.
+ *
+ * @param c the TLS connection.
+ * @param record the TLSPlaintext record to compress.
+ * @param s the ConnectionState to use.
+ *
+ * @return true on success, false on failure.
+ */
+var deflate = function(c, record, s) {
+  var rval = false;
+
+  try {
+    var bytes = c.deflate(record.fragment.getBytes());
+    record.fragment = forge.util.createBuffer(bytes);
+    record.length = bytes.length;
+    rval = true;
+  } catch(ex) {
+    // deflate error, fail out
+  }
+
+  return rval;
+};
+
+/**
+ * Decompresses the TLSCompressed record into a TLSPlaintext record using the
+ * deflate algorithm.
+ *
+ * @param c the TLS connection.
+ * @param record the TLSCompressed record to decompress.
+ * @param s the ConnectionState to use.
+ *
+ * @return true on success, false on failure.
+ */
+var inflate = function(c, record, s) {
+  var rval = false;
+
+  try {
+    var bytes = c.inflate(record.fragment.getBytes());
+    record.fragment = forge.util.createBuffer(bytes);
+    record.length = bytes.length;
+    rval = true;
+  } catch(ex) {
+    // inflate error, fail out
+  }
+
+  return rval;
+};
+
+/**
+ * Reads a TLS variable-length vector from a byte buffer.
+ *
+ * Variable-length vectors are defined by specifying a subrange of legal
+ * lengths, inclusively, using the notation <floor..ceiling>. When these are
+ * encoded, the actual length precedes the vector's contents in the byte
+ * stream. The length will be in the form of a number consuming as many bytes
+ * as required to hold the vector's specified maximum (ceiling) length. A
+ * variable-length vector with an actual length field of zero is referred to
+ * as an empty vector.
+ *
+ * @param b the byte buffer.
+ * @param lenBytes the number of bytes required to store the length.
+ *
+ * @return the resulting byte buffer.
+ */
+var readVector = function(b, lenBytes) {
+  var len = 0;
+  switch(lenBytes) {
+  case 1:
+    len = b.getByte();
+    break;
+  case 2:
+    len = b.getInt16();
+    break;
+  case 3:
+    len = b.getInt24();
+    break;
+  case 4:
+    len = b.getInt32();
+    break;
+  }
+
+  // read vector bytes into a new buffer
+  return forge.util.createBuffer(b.getBytes(len));
+};
+
+/**
+ * Writes a TLS variable-length vector to a byte buffer.
+ *
+ * @param b the byte buffer.
+ * @param lenBytes the number of bytes required to store the length.
+ * @param v the byte buffer vector.
+ */
+var writeVector = function(b, lenBytes, v) {
+  // encode length at the start of the vector, where the number of bytes for
+  // the length is the maximum number of bytes it would take to encode the
+  // vector's ceiling
+  b.putInt(v.length(), lenBytes << 3);
+  b.putBuffer(v);
+};
+
+/**
+ * The tls implementation.
+ */
+var tls = {};
+
+/**
+ * Version: TLS 1.2 = 3.3, TLS 1.1 = 3.2, TLS 1.0 = 3.1. Both TLS 1.1 and
+ * TLS 1.2 were still too new (ie: openSSL didn't implement them) at the time
+ * of this implementation so TLS 1.0 was implemented instead.
+ */
+tls.Versions = {
+  TLS_1_0: {major: 3, minor: 1},
+  TLS_1_1: {major: 3, minor: 2},
+  TLS_1_2: {major: 3, minor: 3}
+};
+tls.SupportedVersions = [
+  tls.Versions.TLS_1_1,
+  tls.Versions.TLS_1_0
+];
+tls.Version = tls.SupportedVersions[0];
+
+/**
+ * Maximum fragment size. True maximum is 16384, but we fragment before that
+ * to allow for unusual small increases during compression.
+ */
+tls.MaxFragment = 16384 - 1024;
+
+/**
+ * Whether this entity is considered the "client" or "server".
+ * enum { server, client } ConnectionEnd;
+ */
+tls.ConnectionEnd = {
+  server: 0,
+  client: 1
+};
+
+/**
+ * Pseudo-random function algorithm used to generate keys from the master
+ * secret.
+ * enum { tls_prf_sha256 } PRFAlgorithm;
+ */
+tls.PRFAlgorithm = {
+  tls_prf_sha256: 0
+};
+
+/**
+ * Bulk encryption algorithms.
+ * enum { null, rc4, des3, aes } BulkCipherAlgorithm;
+ */
+tls.BulkCipherAlgorithm = {
+  none: null,
+  rc4: 0,
+  des3: 1,
+  aes: 2
+};
+
+/**
+ * Cipher types.
+ * enum { stream, block, aead } CipherType;
+ */
+tls.CipherType = {
+  stream: 0,
+  block: 1,
+  aead: 2
+};
+
+/**
+ * MAC (Message Authentication Code) algorithms.
+ * enum { null, hmac_md5, hmac_sha1, hmac_sha256,
+ *   hmac_sha384, hmac_sha512} MACAlgorithm;
+ */
+tls.MACAlgorithm = {
+  none: null,
+  hmac_md5: 0,
+  hmac_sha1: 1,
+  hmac_sha256: 2,
+  hmac_sha384: 3,
+  hmac_sha512: 4
+};
+
+/**
+ * Compression algorithms.
+ * enum { null(0), deflate(1), (255) } CompressionMethod;
+ */
+tls.CompressionMethod = {
+  none: 0,
+  deflate: 1
+};
+
+/**
+ * TLS record content types.
+ * enum {
+ *   change_cipher_spec(20), alert(21), handshake(22),
+ *   application_data(23), (255)
+ * } ContentType;
+ */
+tls.ContentType = {
+  change_cipher_spec: 20,
+  alert: 21,
+  handshake: 22,
+  application_data: 23,
+  heartbeat: 24
+};
+
+/**
+ * TLS handshake types.
+ * enum {
+ *   hello_request(0), client_hello(1), server_hello(2),
+ *   certificate(11), server_key_exchange (12),
+ *   certificate_request(13), server_hello_done(14),
+ *   certificate_verify(15), client_key_exchange(16),
+ *   finished(20), (255)
+ * } HandshakeType;
+ */
+tls.HandshakeType = {
+  hello_request: 0,
+  client_hello: 1,
+  server_hello: 2,
+  certificate: 11,
+  server_key_exchange: 12,
+  certificate_request: 13,
+  server_hello_done: 14,
+  certificate_verify: 15,
+  client_key_exchange: 16,
+  finished: 20
+};
+
+/**
+ * TLS Alert Protocol.
+ *
+ * enum { warning(1), fatal(2), (255) } AlertLevel;
+ *
+ * enum {
+ *   close_notify(0),
+ *   unexpected_message(10),
+ *   bad_record_mac(20),
+ *   decryption_failed(21),
+ *   record_overflow(22),
+ *   decompression_failure(30),
+ *   handshake_failure(40),
+ *   bad_certificate(42),
+ *   unsupported_certificate(43),
+ *   certificate_revoked(44),
+ *   certificate_expired(45),
+ *   certificate_unknown(46),
+ *   illegal_parameter(47),
+ *   unknown_ca(48),
+ *   access_denied(49),
+ *   decode_error(50),
+ *   decrypt_error(51),
+ *   export_restriction(60),
+ *   protocol_version(70),
+ *   insufficient_security(71),
+ *   internal_error(80),
+ *   user_canceled(90),
+ *   no_renegotiation(100),
+ *   (255)
+ * } AlertDescription;
+ *
+ * struct {
+ *   AlertLevel level;
+ *   AlertDescription description;
+ * } Alert;
+ */
+tls.Alert = {};
+tls.Alert.Level = {
+  warning: 1,
+  fatal: 2
+};
+tls.Alert.Description = {
+  close_notify: 0,
+  unexpected_message: 10,
+  bad_record_mac: 20,
+  decryption_failed: 21,
+  record_overflow: 22,
+  decompression_failure: 30,
+  handshake_failure: 40,
+  bad_certificate: 42,
+  unsupported_certificate: 43,
+  certificate_revoked: 44,
+  certificate_expired: 45,
+  certificate_unknown: 46,
+  illegal_parameter: 47,
+  unknown_ca: 48,
+  access_denied: 49,
+  decode_error: 50,
+  decrypt_error: 51,
+  export_restriction: 60,
+  protocol_version: 70,
+  insufficient_security: 71,
+  internal_error: 80,
+  user_canceled: 90,
+  no_renegotiation: 100
+};
+
+/**
+ * TLS Heartbeat Message types.
+ * enum {
+ *   heartbeat_request(1),
+ *   heartbeat_response(2),
+ *   (255)
+ * } HeartbeatMessageType;
+ */
+tls.HeartbeatMessageType = {
+  heartbeat_request: 1,
+  heartbeat_response: 2
+};
+
+/**
+ * Supported cipher suites.
+ */
+tls.CipherSuites = {};
+
+/**
+ * Gets a supported cipher suite from its 2 byte ID.
+ *
+ * @param twoBytes two bytes in a string.
+ *
+ * @return the matching supported cipher suite or null.
+ */
+tls.getCipherSuite = function(twoBytes) {
+  var rval = null;
+  for(var key in tls.CipherSuites) {
+    var cs = tls.CipherSuites[key];
+    if(cs.id[0] === twoBytes.charCodeAt(0) &&
+      cs.id[1] === twoBytes.charCodeAt(1)) {
+      rval = cs;
+      break;
+    }
+  }
+  return rval;
+};
+
+/**
+ * Called when an unexpected record is encountered.
+ *
+ * @param c the connection.
+ * @param record the record.
+ */
+tls.handleUnexpected = function(c, record) {
+  // if connection is client and closed, ignore unexpected messages
+  var ignore = (!c.open && c.entity === tls.ConnectionEnd.client);
+  if(!ignore) {
+    c.error(c, {
+      message: 'Unexpected message. Received TLS record out of order.',
+      send: true,
+      alert: {
+        level: tls.Alert.Level.fatal,
+        description: tls.Alert.Description.unexpected_message
+      }
+    });
+  }
+};
+
+/**
+ * Called when a client receives a HelloRequest record.
+ *
+ * @param c the connection.
+ * @param record the record.
+ * @param length the length of the handshake message.
+ */
+tls.handleHelloRequest = function(c, record, length) {
+  // ignore renegotiation requests from the server during a handshake, but
+  // if handshaking, send a warning alert that renegotiation is denied
+  if(!c.handshaking && c.handshakes > 0) {
+    // send alert warning
+    tls.queue(c, tls.createAlert(c, {
+       level: tls.Alert.Level.warning,
+       description: tls.Alert.Description.no_renegotiation
+    }));
+    tls.flush(c);
+  }
+
+  // continue
+  c.process();
+};
+
+/**
+ * Parses a hello message from a ClientHello or ServerHello record.
+ *
+ * @param record the record to parse.
+ *
+ * @return the parsed message.
+ */
+tls.parseHelloMessage = function(c, record, length) {
+  var msg = null;
+
+  var client = (c.entity === tls.ConnectionEnd.client);
+
+  // minimum of 38 bytes in message
+  if(length < 38) {
+    c.error(c, {
+      message: client ?
+        'Invalid ServerHello message. Message too short.' :
+        'Invalid ClientHello message. Message too short.',
+      send: true,
+      alert: {
+        level: tls.Alert.Level.fatal,
+        description: tls.Alert.Description.illegal_parameter
+      }
+    });
+  } else {
+    // use 'remaining' to calculate # of remaining bytes in the message
+    var b = record.fragment;
+    var remaining = b.length();
+    msg = {
+      version: {
+        major: b.getByte(),
+        minor: b.getByte()
+      },
+      random: forge.util.createBuffer(b.getBytes(32)),
+      session_id: readVector(b, 1),
+      extensions: []
+    };
+    if(client) {
+      msg.cipher_suite = b.getBytes(2);
+      msg.compression_method = b.getByte();
+    } else {
+      msg.cipher_suites = readVector(b, 2);
+      msg.compression_methods = readVector(b, 1);
+    }
+
+    // read extensions if there are any bytes left in the message
+    remaining = length - (remaining - b.length());
+    if(remaining > 0) {
+      // parse extensions
+      var exts = readVector(b, 2);
+      while(exts.length() > 0) {
+        msg.extensions.push({
+          type: [exts.getByte(), exts.getByte()],
+          data: readVector(exts, 2)
+        });
+      }
+
+      // TODO: make extension support modular
+      if(!client) {
+        for(var i = 0; i < msg.extensions.length; ++i) {
+          var ext = msg.extensions[i];
+
+          // support SNI extension
+          if(ext.type[0] === 0x00 && ext.type[1] === 0x00) {
+            // get server name list
+            var snl = readVector(ext.data, 2);
+            while(snl.length() > 0) {
+              // read server name type
+              var snType = snl.getByte();
+
+              // only HostName type (0x00) is known, break out if
+              // another type is detected
+              if(snType !== 0x00) {
+                break;
+              }
+
+              // add host name to server name list
+              c.session.extensions.server_name.serverNameList.push(
+                readVector(snl, 2).getBytes());
+            }
+          }
+        }
+      }
+    }
+
+    // version already set, do not allow version change
+    if(c.session.version) {
+      if(msg.version.major !== c.session.version.major ||
+        msg.version.minor !== c.session.version.minor) {
+        return c.error(c, {
+          message: 'TLS version change is disallowed during renegotiation.',
+          send: true,
+          alert: {
+            level: tls.Alert.Level.fatal,
+            description: tls.Alert.Description.protocol_version
+          }
+        });
+      }
+    }
+
+    // get the chosen (ServerHello) cipher suite
+    if(client) {
+      // FIXME: should be checking configured acceptable cipher suites
+      c.session.cipherSuite = tls.getCipherSuite(msg.cipher_suite);
+    } else {
+      // get a supported preferred (ClientHello) cipher suite
+      // choose the first supported cipher suite
+      var tmp = forge.util.createBuffer(msg.cipher_suites.bytes());
+      while(tmp.length() > 0) {
+        // FIXME: should be checking configured acceptable suites
+        // cipher suites take up 2 bytes
+        c.session.cipherSuite = tls.getCipherSuite(tmp.getBytes(2));
+        if(c.session.cipherSuite !== null) {
+          break;
+        }
+      }
+    }
+
+    // cipher suite not supported
+    if(c.session.cipherSuite === null) {
+      return c.error(c, {
+        message: 'No cipher suites in common.',
+        send: true,
+        alert: {
+          level: tls.Alert.Level.fatal,
+          description: tls.Alert.Description.handshake_failure
+        },
+        cipherSuite: forge.util.bytesToHex(msg.cipher_suite)
+      });
+    }
+
+    // TODO: handle compression methods
+    if(client) {
+      c.session.compressionMethod = msg.compression_method;
+    } else {
+      // no compression
+      c.session.compressionMethod = tls.CompressionMethod.none;
+    }
+  }
+
+  return msg;
+};
+
+/**
+ * Creates security parameters for the given connection based on the given
+ * hello message.
+ *
+ * @param c the TLS connection.
+ * @param msg the hello message.
+ */
+tls.createSecurityParameters = function(c, msg) {
+  /* Note: security params are from TLS 1.2, some values like prf_algorithm
+  are ignored for TLS 1.0/1.1 and the builtin as specified in the spec is
+  used. */
+
+  // TODO: handle other options from server when more supported
+
+  // get client and server randoms
+  var client = (c.entity === tls.ConnectionEnd.client);
+  var msgRandom = msg.random.bytes();
+  var cRandom = client ? c.session.sp.client_random : msgRandom;
+  var sRandom = client ? msgRandom : tls.createRandom().getBytes();
+
+  // create new security parameters
+  c.session.sp = {
+    entity: c.entity,
+    prf_algorithm: tls.PRFAlgorithm.tls_prf_sha256,
+    bulk_cipher_algorithm: null,
+    cipher_type: null,
+    enc_key_length: null,
+    block_length: null,
+    fixed_iv_length: null,
+    record_iv_length: null,
+    mac_algorithm: null,
+    mac_length: null,
+    mac_key_length: null,
+    compression_algorithm: c.session.compressionMethod,
+    pre_master_secret: null,
+    master_secret: null,
+    client_random: cRandom,
+    server_random: sRandom
+  };
+};
+
+/**
+ * Called when a client receives a ServerHello record.
+ *
+ * When a ServerHello message will be sent:
+ *   The server will send this message in response to a client hello message
+ *   when it was able to find an acceptable set of algorithms. If it cannot
+ *   find such a match, it will respond with a handshake failure alert.
+ *
+ * uint24 length;
+ * struct {
+ *   ProtocolVersion server_version;
+ *   Random random;
+ *   SessionID session_id;
+ *   CipherSuite cipher_suite;
+ *   CompressionMethod compression_method;
+ *   select(extensions_present) {
+ *     case false:
+ *       struct {};
+ *     case true:
+ *       Extension extensions<0..2^16-1>;
+ *   };
+ * } ServerHello;
+ *
+ * @param c the connection.
+ * @param record the record.
+ * @param length the length of the handshake message.
+ */
+tls.handleServerHello = function(c, record, length) {
+  var msg = tls.parseHelloMessage(c, record, length);
+  if(c.fail) {
+    return;
+  }
+
+  // ensure server version is compatible
+  if(msg.version.minor <= c.version.minor) {
+    c.version.minor = msg.version.minor;
+  } else {
+    return c.error(c, {
+      message: 'Incompatible TLS version.',
+      send: true,
+      alert: {
+        level: tls.Alert.Level.fatal,
+        description: tls.Alert.Description.protocol_version
+      }
+    });
+  }
+
+  // indicate session version has been set
+  c.session.version = c.version;
+
+  // get the session ID from the message
+  var sessionId = msg.session_id.bytes();
+
+  // if the session ID is not blank and matches the cached one, resume
+  // the session
+  if(sessionId.length > 0 && sessionId === c.session.id) {
+    // resuming session, expect a ChangeCipherSpec next
+    c.expect = SCC;
+    c.session.resuming = true;
+
+    // get new server random
+    c.session.sp.server_random = msg.random.bytes();
+  } else {
+    // not resuming, expect a server Certificate message next
+    c.expect = SCE;
+    c.session.resuming = false;
+
+    // create new security parameters
+    tls.createSecurityParameters(c, msg);
+  }
+
+  // set new session ID
+  c.session.id = sessionId;
+
+  // continue
+  c.process();
+};
+
+/**
+ * Called when a server receives a ClientHello record.
+ *
+ * When a ClientHello message will be sent:
+ *   When a client first connects to a server it is required to send the
+ *   client hello as its first message. The client can also send a client
+ *   hello in response to a hello request or on its own initiative in order
+ *   to renegotiate the security parameters in an existing connection.
+ *
+ * @param c the connection.
+ * @param record the record.
+ * @param length the length of the handshake message.
+ */
+tls.handleClientHello = function(c, record, length) {
+  var msg = tls.parseHelloMessage(c, record, length);
+  if(c.fail) {
+    return;
+  }
+
+  // get the session ID from the message
+  var sessionId = msg.session_id.bytes();
+
+  // see if the given session ID is in the cache
+  var session = null;
+  if(c.sessionCache) {
+    session = c.sessionCache.getSession(sessionId);
+    if(session === null) {
+      // session ID not found
+      sessionId = '';
+    } else if(session.version.major !== msg.version.major ||
+      session.version.minor > msg.version.minor) {
+      // if session version is incompatible with client version, do not resume
+      session = null;
+      sessionId = '';
+    }
+  }
+
+  // no session found to resume, generate a new session ID
+  if(sessionId.length === 0) {
+    sessionId = forge.random.getBytes(32);
+  }
+
+  // update session
+  c.session.id = sessionId;
+  c.session.clientHelloVersion = msg.version;
+  c.session.sp = {};
+  if(session) {
+    // use version and security parameters from resumed session
+    c.version = c.session.version = session.version;
+    c.session.sp = session.sp;
+  } else {
+    // use highest compatible minor version
+    var version;
+    for(var i = 1; i < tls.SupportedVersions.length; ++i) {
+      version = tls.SupportedVersions[i];
+      if(version.minor <= msg.version.minor) {
+        break;
+      }
+    }
+    c.version = {major: version.major, minor: version.minor};
+    c.session.version = c.version;
+  }
+
+  // if a session is set, resume it
+  if(session !== null) {
+    // resuming session, expect a ChangeCipherSpec next
+    c.expect = CCC;
+    c.session.resuming = true;
+
+    // get new client random
+    c.session.sp.client_random = msg.random.bytes();
+  } else {
+    // not resuming, expect a Certificate or ClientKeyExchange
+    c.expect = (c.verifyClient !== false) ? CCE : CKE;
+    c.session.resuming = false;
+
+    // create new security parameters
+    tls.createSecurityParameters(c, msg);
+  }
+
+  // connection now open
+  c.open = true;
+
+  // queue server hello
+  tls.queue(c, tls.createRecord(c, {
+    type: tls.ContentType.handshake,
+    data: tls.createServerHello(c)
+  }));
+
+  if(c.session.resuming) {
+    // queue change cipher spec message
+    tls.queue(c, tls.createRecord(c, {
+      type: tls.ContentType.change_cipher_spec,
+      data: tls.createChangeCipherSpec()
+    }));
+
+    // create pending state
+    c.state.pending = tls.createConnectionState(c);
+
+    // change current write state to pending write state
+    c.state.current.write = c.state.pending.write;
+
+    // queue finished
+    tls.queue(c, tls.createRecord(c, {
+      type: tls.ContentType.handshake,
+      data: tls.createFinished(c)
+    }));
+  } else {
+    // queue server certificate
+    tls.queue(c, tls.createRecord(c, {
+      type: tls.ContentType.handshake,
+      data: tls.createCertificate(c)
+    }));
+
+    if(!c.fail) {
+      // queue server key exchange
+      tls.queue(c, tls.createRecord(c, {
+        type: tls.ContentType.handshake,
+        data: tls.createServerKeyExchange(c)
+      }));
+
+      // request client certificate if set
+      if(c.verifyClient !== false) {
+        // queue certificate request
+        tls.queue(c, tls.createRecord(c, {
+          type: tls.ContentType.handshake,
+          data: tls.createCertificateRequest(c)
+        }));
+      }
+
+      // queue server hello done
+      tls.queue(c, tls.createRecord(c, {
+        type: tls.ContentType.handshake,
+        data: tls.createServerHelloDone(c)
+      }));
+    }
+  }
+
+  // send records
+  tls.flush(c);
+
+  // continue
+  c.process();
+};
+
+/**
+ * Called when a client receives a Certificate record.
+ *
+ * When this message will be sent:
+ *   The server must send a certificate whenever the agreed-upon key exchange
+ *   method is not an anonymous one. This message will always immediately
+ *   follow the server hello message.
+ *
+ * Meaning of this message:
+ *   The certificate type must be appropriate for the selected cipher suite's
+ *   key exchange algorithm, and is generally an X.509v3 certificate. It must
+ *   contain a key which matches the key exchange method, as follows. Unless
+ *   otherwise specified, the signing algorithm for the certificate must be
+ *   the same as the algorithm for the certificate key. Unless otherwise
+ *   specified, the public key may be of any length.
+ *
+ * opaque ASN.1Cert<1..2^24-1>;
+ * struct {
+ *   ASN.1Cert certificate_list<1..2^24-1>;
+ * } Certificate;
+ *
+ * @param c the connection.
+ * @param record the record.
+ * @param length the length of the handshake message.
+ */
+tls.handleCertificate = function(c, record, length) {
+  // minimum of 3 bytes in message
+  if(length < 3) {
+    return c.error(c, {
+      message: 'Invalid Certificate message. Message too short.',
+      send: true,
+      alert: {
+        level: tls.Alert.Level.fatal,
+        description: tls.Alert.Description.illegal_parameter
+      }
+    });
+  }
+
+  var b = record.fragment;
+  var msg = {
+    certificate_list: readVector(b, 3)
+  };
+
+  /* The sender's certificate will be first in the list (chain), each
+    subsequent one that follows will certify the previous one, but root
+    certificates (self-signed) that specify the certificate authority may
+    be omitted under the assumption that clients must already possess it. */
+  var cert, asn1;
+  var certs = [];
+  try {
+    while(msg.certificate_list.length() > 0) {
+      // each entry in msg.certificate_list is a vector with 3 len bytes
+      cert = readVector(msg.certificate_list, 3);
+      asn1 = forge.asn1.fromDer(cert);
+      cert = forge.pki.certificateFromAsn1(asn1, true);
+      certs.push(cert);
+    }
+  } catch(ex) {
+    return c.error(c, {
+      message: 'Could not parse certificate list.',
+      cause: ex,
+      send: true,
+      alert: {
+        level: tls.Alert.Level.fatal,
+        description: tls.Alert.Description.bad_certificate
+      }
+    });
+  }
+
+  // ensure at least 1 certificate was provided if in client-mode
+  // or if verifyClient was set to true to require a certificate
+  // (as opposed to 'optional')
+  var client = (c.entity === tls.ConnectionEnd.client);
+  if((client || c.verifyClient === true) && certs.length === 0) {
+    // error, no certificate
+    c.error(c, {
+      message: client ?
+        'No server certificate provided.' :
+        'No client certificate provided.',
+      send: true,
+      alert: {
+        level: tls.Alert.Level.fatal,
+        description: tls.Alert.Description.illegal_parameter
+      }
+    });
+  } else if(certs.length === 0) {
+    // no certs to verify
+    // expect a ServerKeyExchange or ClientKeyExchange message next
+    c.expect = client ? SKE : CKE;
+  } else {
+    // save certificate in session
+    if(client) {
+      c.session.serverCertificate = certs[0];
+    } else {
+      c.session.clientCertificate = certs[0];
+    }
+
+    if(tls.verifyCertificateChain(c, certs)) {
+      // expect a ServerKeyExchange or ClientKeyExchange message next
+      c.expect = client ? SKE : CKE;
+    }
+  }
+
+  // continue
+  c.process();
+};
+
+/**
+ * Called when a client receives a ServerKeyExchange record.
+ *
+ * When this message will be sent:
+ *   This message will be sent immediately after the server certificate
+ *   message (or the server hello message, if this is an anonymous
+ *   negotiation).
+ *
+ *   The server key exchange message is sent by the server only when the
+ *   server certificate message (if sent) does not contain enough data to
+ *   allow the client to exchange a premaster secret.
+ *
+ * Meaning of this message:
+ *   This message conveys cryptographic information to allow the client to
+ *   communicate the premaster secret: either an RSA public key to encrypt
+ *   the premaster secret with, or a Diffie-Hellman public key with which the
+ *   client can complete a key exchange (with the result being the premaster
+ *   secret.)
+ *
+ * enum {
+ *   dhe_dss, dhe_rsa, dh_anon, rsa, dh_dss, dh_rsa
+ * } KeyExchangeAlgorithm;
+ *
+ * struct {
+ *   opaque dh_p<1..2^16-1>;
+ *   opaque dh_g<1..2^16-1>;
+ *   opaque dh_Ys<1..2^16-1>;
+ * } ServerDHParams;
+ *
+ * struct {
+ *   select(KeyExchangeAlgorithm) {
+ *     case dh_anon:
+ *       ServerDHParams params;
+ *     case dhe_dss:
+ *     case dhe_rsa:
+ *       ServerDHParams params;
+ *       digitally-signed struct {
+ *         opaque client_random[32];
+ *         opaque server_random[32];
+ *         ServerDHParams params;
+ *       } signed_params;
+ *     case rsa:
+ *     case dh_dss:
+ *     case dh_rsa:
+ *       struct {};
+ *   };
+ * } ServerKeyExchange;
+ *
+ * @param c the connection.
+ * @param record the record.
+ * @param length the length of the handshake message.
+ */
+tls.handleServerKeyExchange = function(c, record, length) {
+  // this implementation only supports RSA, no Diffie-Hellman support
+  // so any length > 0 is invalid
+  if(length > 0) {
+    return c.error(c, {
+      message: 'Invalid key parameters. Only RSA is supported.',
+      send: true,
+      alert: {
+        level: tls.Alert.Level.fatal,
+        description: tls.Alert.Description.unsupported_certificate
+      }
+    });
+  }
+
+  // expect an optional CertificateRequest message next
+  c.expect = SCR;
+
+  // continue
+  c.process();
+};
+
+/**
+ * Called when a client receives a ClientKeyExchange record.
+ *
+ * @param c the connection.
+ * @param record the record.
+ * @param length the length of the handshake message.
+ */
+tls.handleClientKeyExchange = function(c, record, length) {
+  // this implementation only supports RSA, no Diffie-Hellman support
+  // so any length < 48 is invalid
+  if(length < 48) {
+    return c.error(c, {
+      message: 'Invalid key parameters. Only RSA is supported.',
+      send: true,
+      alert: {
+        level: tls.Alert.Level.fatal,
+        description: tls.Alert.Description.unsupported_certificate
+      }
+    });
+  }
+
+  var b = record.fragment;
+  var msg = {
+    enc_pre_master_secret: readVector(b, 2).getBytes()
+  };
+
+  // do rsa decryption
+  var privateKey = null;
+  if(c.getPrivateKey) {
+    try {
+      privateKey = c.getPrivateKey(c, c.session.serverCertificate);
+      privateKey = forge.pki.privateKeyFromPem(privateKey);
+    } catch(ex) {
+      c.error(c, {
+        message: 'Could not get private key.',
+        cause: ex,
+        send: true,
+        alert: {
+          level: tls.Alert.Level.fatal,
+          description: tls.Alert.Description.internal_error
+        }
+      });
+    }
+  }
+
+  if(privateKey === null) {
+    return c.error(c, {
+      message: 'No private key set.',
+      send: true,
+      alert: {
+        level: tls.Alert.Level.fatal,
+        description: tls.Alert.Description.internal_error
+      }
+    });
+  }
+
+  try {
+    // decrypt 48-byte pre-master secret
+    var sp = c.session.sp;
+    sp.pre_master_secret = privateKey.decrypt(msg.enc_pre_master_secret);
+
+    // ensure client hello version matches first 2 bytes
+    var version = c.session.clientHelloVersion;
+    if(version.major !== sp.pre_master_secret.charCodeAt(0) ||
+      version.minor !== sp.pre_master_secret.charCodeAt(1)) {
+      // error, do not send alert (see BLEI attack below)
+      throw new Error('TLS version rollback attack detected.');
+    }
+  } catch(ex) {
+    /* Note: Daniel Bleichenbacher [BLEI] can be used to attack a
+      TLS server which is using PKCS#1 encoded RSA, so instead of
+      failing here, we generate 48 random bytes and use that as
+      the pre-master secret. */
+    sp.pre_master_secret = forge.random.getBytes(48);
+  }
+
+  // expect a CertificateVerify message if a Certificate was received that
+  // does not have fixed Diffie-Hellman params, otherwise expect
+  // ChangeCipherSpec
+  c.expect = CCC;
+  if(c.session.clientCertificate !== null) {
+    // only RSA support, so expect CertificateVerify
+    // TODO: support Diffie-Hellman
+    c.expect = CCV;
+  }
+
+  // continue
+  c.process();
+};
+
+/**
+ * Called when a client receives a CertificateRequest record.
+ *
+ * When this message will be sent:
+ *   A non-anonymous server can optionally request a certificate from the
+ *   client, if appropriate for the selected cipher suite. This message, if
+ *   sent, will immediately follow the Server Key Exchange message (if it is
+ *   sent; otherwise, the Server Certificate message).
+ *
+ * enum {
+ *   rsa_sign(1), dss_sign(2), rsa_fixed_dh(3), dss_fixed_dh(4),
+ *   rsa_ephemeral_dh_RESERVED(5), dss_ephemeral_dh_RESERVED(6),
+ *   fortezza_dms_RESERVED(20), (255)
+ * } ClientCertificateType;
+ *
+ * opaque DistinguishedName<1..2^16-1>;
+ *
+ * struct {
+ *   ClientCertificateType certificate_types<1..2^8-1>;
+ *   SignatureAndHashAlgorithm supported_signature_algorithms<2^16-1>;
+ *   DistinguishedName certificate_authorities<0..2^16-1>;
+ * } CertificateRequest;
+ *
+ * @param c the connection.
+ * @param record the record.
+ * @param length the length of the handshake message.
+ */
+tls.handleCertificateRequest = function(c, record, length) {
+  // minimum of 3 bytes in message
+  if(length < 3) {
+    return c.error(c, {
+      message: 'Invalid CertificateRequest. Message too short.',
+      send: true,
+      alert: {
+        level: tls.Alert.Level.fatal,
+        description: tls.Alert.Description.illegal_parameter
+      }
+    });
+  }
+
+  // TODO: TLS 1.2+ has different format including
+  // SignatureAndHashAlgorithm after cert types
+  var b = record.fragment;
+  var msg = {
+    certificate_types: readVector(b, 1),
+    certificate_authorities: readVector(b, 2)
+  };
+
+  // save certificate request in session
+  c.session.certificateRequest = msg;
+
+  // expect a ServerHelloDone message next
+  c.expect = SHD;
+
+  // continue
+  c.process();
+};
+
+/**
+ * Called when a server receives a CertificateVerify record.
+ *
+ * @param c the connection.
+ * @param record the record.
+ * @param length the length of the handshake message.
+ */
+tls.handleCertificateVerify = function(c, record, length) {
+  if(length < 2) {
+    return c.error(c, {
+      message: 'Invalid CertificateVerify. Message too short.',
+      send: true,
+      alert: {
+        level: tls.Alert.Level.fatal,
+        description: tls.Alert.Description.illegal_parameter
+      }
+    });
+  }
+
+  // rewind to get full bytes for message so it can be manually
+  // digested below (special case for CertificateVerify messages because
+  // they must be digested *after* handling as opposed to all others)
+  var b = record.fragment;
+  b.read -= 4;
+  var msgBytes = b.bytes();
+  b.read += 4;
+
+  var msg = {
+    signature: readVector(b, 2).getBytes()
+  };
+
+  // TODO: add support for DSA
+
+  // generate data to verify
+  var verify = forge.util.createBuffer();
+  verify.putBuffer(c.session.md5.digest());
+  verify.putBuffer(c.session.sha1.digest());
+  verify = verify.getBytes();
+
+  try {
+    var cert = c.session.clientCertificate;
+    /*b = forge.pki.rsa.decrypt(
+      msg.signature, cert.publicKey, true, verify.length);
+    if(b !== verify) {*/
+    if(!cert.publicKey.verify(verify, msg.signature, 'NONE')) {
+      throw new Error('CertificateVerify signature does not match.');
+    }
+
+    // digest message now that it has been handled
+    c.session.md5.update(msgBytes);
+    c.session.sha1.update(msgBytes);
+  } catch(ex) {
+    return c.error(c, {
+      message: 'Bad signature in CertificateVerify.',
+      send: true,
+      alert: {
+        level: tls.Alert.Level.fatal,
+        description: tls.Alert.Description.handshake_failure
+      }
+    });
+  }
+
+  // expect ChangeCipherSpec
+  c.expect = CCC;
+
+  // continue
+  c.process();
+};
+
+/**
+ * Called when a client receives a ServerHelloDone record.
+ *
+ * When this message will be sent:
+ *   The server hello done message is sent by the server to indicate the end
+ *   of the server hello and associated messages. After sending this message
+ *   the server will wait for a client response.
+ *
+ * Meaning of this message:
+ *   This message means that the server is done sending messages to support
+ *   the key exchange, and the client can proceed with its phase of the key
+ *   exchange.
+ *
+ *   Upon receipt of the server hello done message the client should verify
+ *   that the server provided a valid certificate if required and check that
+ *   the server hello parameters are acceptable.
+ *
+ * struct {} ServerHelloDone;
+ *
+ * @param c the connection.
+ * @param record the record.
+ * @param length the length of the handshake message.
+ */
+tls.handleServerHelloDone = function(c, record, length) {
+  // len must be 0 bytes
+  if(length > 0) {
+    return c.error(c, {
+      message: 'Invalid ServerHelloDone message. Invalid length.',
+      send: true,
+      alert: {
+        level: tls.Alert.Level.fatal,
+        description: tls.Alert.Description.record_overflow
+      }
+    });
+  }
+
+  if(c.session.serverCertificate === null) {
+    // no server certificate was provided
+    var error = {
+      message: 'No server certificate provided. Not enough security.',
+      send: true,
+      alert: {
+        level: tls.Alert.Level.fatal,
+        description: tls.Alert.Description.insufficient_security
+      }
+    };
+
+    // call application callback
+    var depth = 0;
+    var ret = c.verify(c, error.alert.description, depth, []);
+    if(ret !== true) {
+      // check for custom alert info
+      if(ret || ret === 0) {
+        // set custom message and alert description
+        if(typeof ret === 'object' && !forge.util.isArray(ret)) {
+          if(ret.message) {
+            error.message = ret.message;
+          }
+          if(ret.alert) {
+            error.alert.description = ret.alert;
+          }
+        } else if(typeof ret === 'number') {
+          // set custom alert description
+          error.alert.description = ret;
+        }
+      }
+    }
+
+    // send error even if accepted, the RSA key exchange needs the server
+    // certificate
+    return c.error(c, error);
+  }
+
+  // create client certificate message if requested
+  if(c.session.certificateRequest !== null) {
+    record = tls.createRecord(c, {
+      type: tls.ContentType.handshake,
+      data: tls.createCertificate(c)
+    });
+    tls.queue(c, record);
+  }
+
+  // create client key exchange message
+  record = tls.createRecord(c, {
+     type: tls.ContentType.handshake,
+     data: tls.createClientKeyExchange(c)
+  });
+  tls.queue(c, record);
+
+  // expect no messages until the following callback has been called
+  c.expect = SER;
+
+  // create callback to handle client signature (for client-certs)
+  var callback = function(c, signature) {
+    if(c.session.certificateRequest !== null &&
+      c.session.clientCertificate !== null) {
+      // create certificate verify message
+      tls.queue(c, tls.createRecord(c, {
+        type: tls.ContentType.handshake,
+        data: tls.createCertificateVerify(c, signature)
+      }));
+    }
+
+    // create change cipher spec message
+    tls.queue(c, tls.createRecord(c, {
+      type: tls.ContentType.change_cipher_spec,
+      data: tls.createChangeCipherSpec()
+    }));
+
+    // create pending state
+    c.state.pending = tls.createConnectionState(c);
+
+    // change current write state to pending write state
+    c.state.current.write = c.state.pending.write;
+
+    // create finished message
+    tls.queue(c, tls.createRecord(c, {
+      type: tls.ContentType.handshake,
+      data: tls.createFinished(c)
+    }));
+
+    // expect a server ChangeCipherSpec message next
+    c.expect = SCC;
+
+    // send records
+    tls.flush(c);
+
+    // continue
+    c.process();
+  };
+
+  // if there is no certificate request or no client certificate, do
+  // callback immediately
+  if(c.session.certificateRequest === null ||
+    c.session.clientCertificate === null) {
+    return callback(c, null);
+  }
+
+  // otherwise get the client signature
+  tls.getClientSignature(c, callback);
+};
+
+/**
+ * Called when a ChangeCipherSpec record is received.
+ *
+ * @param c the connection.
+ * @param record the record.
+ */
+tls.handleChangeCipherSpec = function(c, record) {
+  if(record.fragment.getByte() !== 0x01) {
+    return c.error(c, {
+      message: 'Invalid ChangeCipherSpec message received.',
+      send: true,
+      alert: {
+        level: tls.Alert.Level.fatal,
+        description: tls.Alert.Description.illegal_parameter
+      }
+    });
+  }
+
+  // create pending state if:
+  // 1. Resuming session in client mode OR
+  // 2. NOT resuming session in server mode
+  var client = (c.entity === tls.ConnectionEnd.client);
+  if((c.session.resuming && client) || (!c.session.resuming && !client)) {
+    c.state.pending = tls.createConnectionState(c);
+  }
+
+  // change current read state to pending read state
+  c.state.current.read = c.state.pending.read;
+
+  // clear pending state if:
+  // 1. NOT resuming session in client mode OR
+  // 2. resuming a session in server mode
+  if((!c.session.resuming && client) || (c.session.resuming && !client)) {
+    c.state.pending = null;
+  }
+
+  // expect a Finished record next
+  c.expect = client ? SFI : CFI;
+
+  // continue
+  c.process();
+};
+
+/**
+ * Called when a Finished record is received.
+ *
+ * When this message will be sent:
+ *   A finished message is always sent immediately after a change
+ *   cipher spec message to verify that the key exchange and
+ *   authentication processes were successful. It is essential that a
+ *   change cipher spec message be received between the other
+ *   handshake messages and the Finished message.
+ *
+ * Meaning of this message:
+ *   The finished message is the first protected with the just-
+ *   negotiated algorithms, keys, and secrets. Recipients of finished
+ *   messages must verify that the contents are correct.  Once a side
+ *   has sent its Finished message and received and validated the
+ *   Finished message from its peer, it may begin to send and receive
+ *   application data over the connection.
+ *
+ * struct {
+ *   opaque verify_data[verify_data_length];
+ * } Finished;
+ *
+ * verify_data
+ *   PRF(master_secret, finished_label, Hash(handshake_messages))
+ *     [0..verify_data_length-1];
+ *
+ * finished_label
+ *   For Finished messages sent by the client, the string
+ *   "client finished". For Finished messages sent by the server, the
+ *   string "server finished".
+ *
+ * verify_data_length depends on the cipher suite. If it is not specified
+ * by the cipher suite, then it is 12. Versions of TLS < 1.2 always used
+ * 12 bytes.
+ *
+ * @param c the connection.
+ * @param record the record.
+ * @param length the length of the handshake message.
+ */
+tls.handleFinished = function(c, record, length) {
+  // rewind to get full bytes for message so it can be manually
+  // digested below (special case for Finished messages because they
+  // must be digested *after* handling as opposed to all others)
+  var b = record.fragment;
+  b.read -= 4;
+  var msgBytes = b.bytes();
+  b.read += 4;
+
+  // message contains only verify_data
+  var vd = record.fragment.getBytes();
+
+  // ensure verify data is correct
+  b = forge.util.createBuffer();
+  b.putBuffer(c.session.md5.digest());
+  b.putBuffer(c.session.sha1.digest());
+
+  // set label based on entity type
+  var client = (c.entity === tls.ConnectionEnd.client);
+  var label = client ? 'server finished' : 'client finished';
+
+  // TODO: determine prf function and verify length for TLS 1.2
+  var sp = c.session.sp;
+  var vdl = 12;
+  var prf = prf_TLS1;
+  b = prf(sp.master_secret, label, b.getBytes(), vdl);
+  if(b.getBytes() !== vd) {
+    return c.error(c, {
+      message: 'Invalid verify_data in Finished message.',
+      send: true,
+      alert: {
+        level: tls.Alert.Level.fatal,
+        description: tls.Alert.Description.decrypt_error
+      }
+    });
+  }
+
+  // digest finished message now that it has been handled
+  c.session.md5.update(msgBytes);
+  c.session.sha1.update(msgBytes);
+
+  // resuming session as client or NOT resuming session as server
+  if((c.session.resuming && client) || (!c.session.resuming && !client)) {
+    // create change cipher spec message
+    tls.queue(c, tls.createRecord(c, {
+      type: tls.ContentType.change_cipher_spec,
+      data: tls.createChangeCipherSpec()
+    }));
+
+    // change current write state to pending write state, clear pending
+    c.state.current.write = c.state.pending.write;
+    c.state.pending = null;
+
+    // create finished message
+    tls.queue(c, tls.createRecord(c, {
+      type: tls.ContentType.handshake,
+      data: tls.createFinished(c)
+    }));
+  }
+
+  // expect application data next
+  c.expect = client ? SAD : CAD;
+
+  // handshake complete
+  c.handshaking = false;
+  ++c.handshakes;
+
+  // save access to peer certificate
+  c.peerCertificate = client ?
+    c.session.serverCertificate : c.session.clientCertificate;
+
+  // send records
+  tls.flush(c);
+
+  // now connected
+  c.isConnected = true;
+  c.connected(c);
+
+  // continue
+  c.process();
+};
+
+/**
+ * Called when an Alert record is received.
+ *
+ * @param c the connection.
+ * @param record the record.
+ */
+tls.handleAlert = function(c, record) {
+  // read alert
+  var b = record.fragment;
+  var alert = {
+    level: b.getByte(),
+    description: b.getByte()
+  };
+
+  // TODO: consider using a table?
+  // get appropriate message
+  var msg;
+  switch(alert.description) {
+  case tls.Alert.Description.close_notify:
+    msg = 'Connection closed.';
+    break;
+  case tls.Alert.Description.unexpected_message:
+    msg = 'Unexpected message.';
+    break;
+  case tls.Alert.Description.bad_record_mac:
+    msg = 'Bad record MAC.';
+    break;
+  case tls.Alert.Description.decryption_failed:
+    msg = 'Decryption failed.';
+    break;
+  case tls.Alert.Description.record_overflow:
+    msg = 'Record overflow.';
+    break;
+  case tls.Alert.Description.decompression_failure:
+    msg = 'Decompression failed.';
+    break;
+  case tls.Alert.Description.handshake_failure:
+    msg = 'Handshake failure.';
+    break;
+  case tls.Alert.Description.bad_certificate:
+    msg = 'Bad certificate.';
+    break;
+  case tls.Alert.Description.unsupported_certificate:
+    msg = 'Unsupported certificate.';
+    break;
+  case tls.Alert.Description.certificate_revoked:
+    msg = 'Certificate revoked.';
+    break;
+  case tls.Alert.Description.certificate_expired:
+    msg = 'Certificate expired.';
+    break;
+  case tls.Alert.Description.certificate_unknown:
+    msg = 'Certificate unknown.';
+    break;
+  case tls.Alert.Description.illegal_parameter:
+    msg = 'Illegal parameter.';
+    break;
+  case tls.Alert.Description.unknown_ca:
+    msg = 'Unknown certificate authority.';
+    break;
+  case tls.Alert.Description.access_denied:
+    msg = 'Access denied.';
+    break;
+  case tls.Alert.Description.decode_error:
+    msg = 'Decode error.';
+    break;
+  case tls.Alert.Description.decrypt_error:
+    msg = 'Decrypt error.';
+    break;
+  case tls.Alert.Description.export_restriction:
+    msg = 'Export restriction.';
+    break;
+  case tls.Alert.Description.protocol_version:
+    msg = 'Unsupported protocol version.';
+    break;
+  case tls.Alert.Description.insufficient_security:
+    msg = 'Insufficient security.';
+    break;
+  case tls.Alert.Description.internal_error:
+    msg = 'Internal error.';
+    break;
+  case tls.Alert.Description.user_canceled:
+    msg = 'User canceled.';
+    break;
+  case tls.Alert.Description.no_renegotiation:
+    msg = 'Renegotiation not supported.';
+    break;
+  default:
+    msg = 'Unknown error.';
+    break;
+  }
+
+  // close connection on close_notify, not an error
+  if(alert.description === tls.Alert.Description.close_notify) {
+    return c.close();
+  }
+
+  // call error handler
+  c.error(c, {
+    message: msg,
+    send: false,
+    // origin is the opposite end
+    origin: (c.entity === tls.ConnectionEnd.client) ? 'server' : 'client',
+    alert: alert
+  });
+
+  // continue
+  c.process();
+};
+
+/**
+ * Called when a Handshake record is received.
+ *
+ * @param c the connection.
+ * @param record the record.
+ */
+tls.handleHandshake = function(c, record) {
+  // get the handshake type and message length
+  var b = record.fragment;
+  var type = b.getByte();
+  var length = b.getInt24();
+
+  // see if the record fragment doesn't yet contain the full message
+  if(length > b.length()) {
+    // cache the record, clear its fragment, and reset the buffer read
+    // pointer before the type and length were read
+    c.fragmented = record;
+    record.fragment = forge.util.createBuffer();
+    b.read -= 4;
+
+    // continue
+    return c.process();
+  }
+
+  // full message now available, clear cache, reset read pointer to
+  // before type and length
+  c.fragmented = null;
+  b.read -= 4;
+
+  // save the handshake bytes for digestion after handler is found
+  // (include type and length of handshake msg)
+  var bytes = b.bytes(length + 4);
+
+  // restore read pointer
+  b.read += 4;
+
+  // handle expected message
+  if(type in hsTable[c.entity][c.expect]) {
+    // initialize server session
+    if(c.entity === tls.ConnectionEnd.server && !c.open && !c.fail) {
+      c.handshaking = true;
+      c.session = {
+        version: null,
+        extensions: {
+          server_name: {
+            serverNameList: []
+          }
+        },
+        cipherSuite: null,
+        compressionMethod: null,
+        serverCertificate: null,
+        clientCertificate: null,
+        md5: forge.md.md5.create(),
+        sha1: forge.md.sha1.create()
+      };
+    }
+
+    /* Update handshake messages digest. Finished and CertificateVerify
+      messages are not digested here. They can't be digested as part of
+      the verify_data that they contain. These messages are manually
+      digested in their handlers. HelloRequest messages are simply never
+      included in the handshake message digest according to spec. */
+    if(type !== tls.HandshakeType.hello_request &&
+      type !== tls.HandshakeType.certificate_verify &&
+      type !== tls.HandshakeType.finished) {
+      c.session.md5.update(bytes);
+      c.session.sha1.update(bytes);
+    }
+
+    // handle specific handshake type record
+    hsTable[c.entity][c.expect][type](c, record, length);
+  } else {
+    // unexpected record
+    tls.handleUnexpected(c, record);
+  }
+};
+
+/**
+ * Called when an ApplicationData record is received.
+ *
+ * @param c the connection.
+ * @param record the record.
+ */
+tls.handleApplicationData = function(c, record) {
+  // buffer data, notify that its ready
+  c.data.putBuffer(record.fragment);
+  c.dataReady(c);
+
+  // continue
+  c.process();
+};
+
+/**
+ * Called when a Heartbeat record is received.
+ *
+ * @param c the connection.
+ * @param record the record.
+ */
+tls.handleHeartbeat = function(c, record) {
+  // get the heartbeat type and payload
+  var b = record.fragment;
+  var type = b.getByte();
+  var length = b.getInt16();
+  var payload = b.getBytes(length);
+
+  if(type === tls.HeartbeatMessageType.heartbeat_request) {
+    // discard request before the first handshake is complete, during
+    // handshake, or if length is too large
+    if(c.handshakes === 0 || c.handshaking || length > payload.length) {
+      // continue
+      return c.process();
+    }
+    // retransmit payload
+    tls.queue(c, tls.createRecord(c, {
+      type: tls.ContentType.heartbeat,
+      data: tls.createHeartbeat(
+        tls.HeartbeatMessageType.heartbeat_response, payload)
+    }));
+    tls.flush(c);
+  } else if(type === tls.HeartbeatMessageType.heartbeat_response) {
+    // check payload against expected payload, discard heartbeat if no match
+    if(payload !== c.expectedHeartbeatPayload) {
+      // continue
+      return c.process();
+    }
+
+    // notify that a valid heartbeat was received
+    if(c.heartbeatReceived) {
+      c.heartbeatReceived(c, forge.util.createBuffer(payload));
+    }
+  }
+
+  // continue
+  c.process();
+};
+
+/**
+ * The transistional state tables for receiving TLS records. It maps the
+ * current TLS engine state and a received record to a function to handle the
+ * record and update the state.
+ *
+ * For instance, if the current state is SHE, then the TLS engine is expecting
+ * a ServerHello record. Once a record is received, the handler function is
+ * looked up using the state SHE and the record's content type.
+ *
+ * The resulting function will either be an error handler or a record handler.
+ * The function will take whatever action is appropriate and update the state
+ * for the next record.
+ *
+ * The states are all based on possible server record types. Note that the
+ * client will never specifically expect to receive a HelloRequest or an alert
+ * from the server so there is no state that reflects this. These messages may
+ * occur at any time.
+ *
+ * There are two tables for mapping states because there is a second tier of
+ * types for handshake messages. Once a record with a content type of handshake
+ * is received, the handshake record handler will look up the handshake type in
+ * the secondary map to get its appropriate handler.
+ *
+ * Valid message orders are as follows:
+ *
+ * =======================FULL HANDSHAKE======================
+ * Client                                               Server
+ *
+ * ClientHello                  -------->
+ *                                                 ServerHello
+ *                                                Certificate*
+ *                                          ServerKeyExchange*
+ *                                         CertificateRequest*
+ *                              <--------      ServerHelloDone
+ * Certificate*
+ * ClientKeyExchange
+ * CertificateVerify*
+ * [ChangeCipherSpec]
+ * Finished                     -------->
+ *                                          [ChangeCipherSpec]
+ *                              <--------             Finished
+ * Application Data             <------->     Application Data
+ *
+ * =====================SESSION RESUMPTION=====================
+ * Client                                                Server
+ *
+ * ClientHello                   -------->
+ *                                                  ServerHello
+ *                                           [ChangeCipherSpec]
+ *                               <--------             Finished
+ * [ChangeCipherSpec]
+ * Finished                      -------->
+ * Application Data              <------->     Application Data
+ */
+// client expect states (indicate which records are expected to be received)
+var SHE = 0; // rcv server hello
+var SCE = 1; // rcv server certificate
+var SKE = 2; // rcv server key exchange
+var SCR = 3; // rcv certificate request
+var SHD = 4; // rcv server hello done
+var SCC = 5; // rcv change cipher spec
+var SFI = 6; // rcv finished
+var SAD = 7; // rcv application data
+var SER = 8; // not expecting any messages at this point
+
+// server expect states
+var CHE = 0; // rcv client hello
+var CCE = 1; // rcv client certificate
+var CKE = 2; // rcv client key exchange
+var CCV = 3; // rcv certificate verify
+var CCC = 4; // rcv change cipher spec
+var CFI = 5; // rcv finished
+var CAD = 6; // rcv application data
+var CER = 7; // not expecting any messages at this point
+
+// map client current expect state and content type to function
+var __ = tls.handleUnexpected;
+var R0 = tls.handleChangeCipherSpec;
+var R1 = tls.handleAlert;
+var R2 = tls.handleHandshake;
+var R3 = tls.handleApplicationData;
+var R4 = tls.handleHeartbeat;
+var ctTable = [];
+ctTable[tls.ConnectionEnd.client] = [
+//      CC,AL,HS,AD,HB
+/*SHE*/[__,R1,R2,__,R4],
+/*SCE*/[__,R1,R2,__,R4],
+/*SKE*/[__,R1,R2,__,R4],
+/*SCR*/[__,R1,R2,__,R4],
+/*SHD*/[__,R1,R2,__,R4],
+/*SCC*/[R0,R1,__,__,R4],
+/*SFI*/[__,R1,R2,__,R4],
+/*SAD*/[__,R1,R2,R3,R4],
+/*SER*/[__,R1,R2,__,R4]
+];
+
+// map server current expect state and content type to function
+ctTable[tls.ConnectionEnd.server] = [
+//      CC,AL,HS,AD
+/*CHE*/[__,R1,R2,__,R4],
+/*CCE*/[__,R1,R2,__,R4],
+/*CKE*/[__,R1,R2,__,R4],
+/*CCV*/[__,R1,R2,__,R4],
+/*CCC*/[R0,R1,__,__,R4],
+/*CFI*/[__,R1,R2,__,R4],
+/*CAD*/[__,R1,R2,R3,R4],
+/*CER*/[__,R1,R2,__,R4]
+];
+
+// map client current expect state and handshake type to function
+var H0 = tls.handleHelloRequest;
+var H1 = tls.handleServerHello;
+var H2 = tls.handleCertificate;
+var H3 = tls.handleServerKeyExchange;
+var H4 = tls.handleCertificateRequest;
+var H5 = tls.handleServerHelloDone;
+var H6 = tls.handleFinished;
+var hsTable = [];
+hsTable[tls.ConnectionEnd.client] = [
+//      HR,01,SH,03,04,05,06,07,08,09,10,SC,SK,CR,HD,15,CK,17,18,19,FI
+/*SHE*/[__,__,H1,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__],
+/*SCE*/[H0,__,__,__,__,__,__,__,__,__,__,H2,H3,H4,H5,__,__,__,__,__,__],
+/*SKE*/[H0,__,__,__,__,__,__,__,__,__,__,__,H3,H4,H5,__,__,__,__,__,__],
+/*SCR*/[H0,__,__,__,__,__,__,__,__,__,__,__,__,H4,H5,__,__,__,__,__,__],
+/*SHD*/[H0,__,__,__,__,__,__,__,__,__,__,__,__,__,H5,__,__,__,__,__,__],
+/*SCC*/[H0,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__],
+/*SFI*/[H0,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,H6],
+/*SAD*/[H0,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__],
+/*SER*/[H0,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__]
+];
+
+// map server current expect state and handshake type to function
+// Note: CAD[CH] does not map to FB because renegotiation is prohibited
+var H7 = tls.handleClientHello;
+var H8 = tls.handleClientKeyExchange;
+var H9 = tls.handleCertificateVerify;
+hsTable[tls.ConnectionEnd.server] = [
+//      01,CH,02,03,04,05,06,07,08,09,10,CC,12,13,14,CV,CK,17,18,19,FI
+/*CHE*/[__,H7,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__],
+/*CCE*/[__,__,__,__,__,__,__,__,__,__,__,H2,__,__,__,__,__,__,__,__,__],
+/*CKE*/[__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,H8,__,__,__,__],
+/*CCV*/[__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,H9,__,__,__,__,__],
+/*CCC*/[__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__],
+/*CFI*/[__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,H6],
+/*CAD*/[__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__],
+/*CER*/[__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__]
+];
+
+/**
+ * Generates the master_secret and keys using the given security parameters.
+ *
+ * The security parameters for a TLS connection state are defined as such:
+ *
+ * struct {
+ *   ConnectionEnd          entity;
+ *   PRFAlgorithm           prf_algorithm;
+ *   BulkCipherAlgorithm    bulk_cipher_algorithm;
+ *   CipherType             cipher_type;
+ *   uint8                  enc_key_length;
+ *   uint8                  block_length;
+ *   uint8                  fixed_iv_length;
+ *   uint8                  record_iv_length;
+ *   MACAlgorithm           mac_algorithm;
+ *   uint8                  mac_length;
+ *   uint8                  mac_key_length;
+ *   CompressionMethod      compression_algorithm;
+ *   opaque                 master_secret[48];
+ *   opaque                 client_random[32];
+ *   opaque                 server_random[32];
+ * } SecurityParameters;
+ *
+ * Note that this definition is from TLS 1.2. In TLS 1.0 some of these
+ * parameters are ignored because, for instance, the PRFAlgorithm is a
+ * builtin-fixed algorithm combining iterations of MD5 and SHA-1 in TLS 1.0.
+ *
+ * The Record Protocol requires an algorithm to generate keys required by the
+ * current connection state.
+ *
+ * The master secret is expanded into a sequence of secure bytes, which is then
+ * split to a client write MAC key, a server write MAC key, a client write
+ * encryption key, and a server write encryption key. In TLS 1.0 a client write
+ * IV and server write IV are also generated. Each of these is generated from
+ * the byte sequence in that order. Unused values are empty. In TLS 1.2, some
+ * AEAD ciphers may additionally require a client write IV and a server write
+ * IV (see Section 6.2.3.3).
+ *
+ * When keys, MAC keys, and IVs are generated, the master secret is used as an
+ * entropy source.
+ *
+ * To generate the key material, compute:
+ *
+ * master_secret = PRF(pre_master_secret, "master secret",
+ *                     ClientHello.random + ServerHello.random)
+ *
+ * key_block = PRF(SecurityParameters.master_secret,
+ *                 "key expansion",
+ *                 SecurityParameters.server_random +
+ *                 SecurityParameters.client_random);
+ *
+ * until enough output has been generated. Then, the key_block is
+ * partitioned as follows:
+ *
+ * client_write_MAC_key[SecurityParameters.mac_key_length]
+ * server_write_MAC_key[SecurityParameters.mac_key_length]
+ * client_write_key[SecurityParameters.enc_key_length]
+ * server_write_key[SecurityParameters.enc_key_length]
+ * client_write_IV[SecurityParameters.fixed_iv_length]
+ * server_write_IV[SecurityParameters.fixed_iv_length]
+ *
+ * In TLS 1.2, the client_write_IV and server_write_IV are only generated for
+ * implicit nonce techniques as described in Section 3.2.1 of [AEAD]. This
+ * implementation uses TLS 1.0 so IVs are generated.
+ *
+ * Implementation note: The currently defined cipher suite which requires the
+ * most material is AES_256_CBC_SHA256. It requires 2 x 32 byte keys and 2 x 32
+ * byte MAC keys, for a total 128 bytes of key material. In TLS 1.0 it also
+ * requires 2 x 16 byte IVs, so it actually takes 160 bytes of key material.
+ *
+ * @param c the connection.
+ * @param sp the security parameters to use.
+ *
+ * @return the security keys.
+ */
+tls.generateKeys = function(c, sp) {
+  // TLS_RSA_WITH_AES_128_CBC_SHA (required to be compliant with TLS 1.2) &
+  // TLS_RSA_WITH_AES_256_CBC_SHA are the only cipher suites implemented
+  // at present
+
+  // TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA is required to be compliant with
+  // TLS 1.0 but we don't care right now because AES is better and we have
+  // an implementation for it
+
+  // TODO: TLS 1.2 implementation
+  /*
+  // determine the PRF
+  var prf;
+  switch(sp.prf_algorithm) {
+  case tls.PRFAlgorithm.tls_prf_sha256:
+    prf = prf_sha256;
+    break;
+  default:
+    // should never happen
+    throw new Error('Invalid PRF');
+  }
+  */
+
+  // TLS 1.0/1.1 implementation
+  var prf = prf_TLS1;
+
+  // concatenate server and client random
+  var random = sp.client_random + sp.server_random;
+
+  // only create master secret if session is new
+  if(!c.session.resuming) {
+    // create master secret, clean up pre-master secret
+    sp.master_secret = prf(
+      sp.pre_master_secret, 'master secret', random, 48).bytes();
+    sp.pre_master_secret = null;
+  }
+
+  // generate the amount of key material needed
+  random = sp.server_random + sp.client_random;
+  var length = 2 * sp.mac_key_length + 2 * sp.enc_key_length;
+
+  // include IV for TLS/1.0
+  var tls10 = (c.version.major === tls.Versions.TLS_1_0.major &&
+    c.version.minor === tls.Versions.TLS_1_0.minor);
+  if(tls10) {
+    length += 2 * sp.fixed_iv_length;
+  }
+  var km = prf(sp.master_secret, 'key expansion', random, length);
+
+  // split the key material into the MAC and encryption keys
+  var rval = {
+    client_write_MAC_key: km.getBytes(sp.mac_key_length),
+    server_write_MAC_key: km.getBytes(sp.mac_key_length),
+    client_write_key: km.getBytes(sp.enc_key_length),
+    server_write_key: km.getBytes(sp.enc_key_length)
+  };
+
+  // include TLS 1.0 IVs
+  if(tls10) {
+    rval.client_write_IV = km.getBytes(sp.fixed_iv_length);
+    rval.server_write_IV = km.getBytes(sp.fixed_iv_length);
+  }
+
+  return rval;
+};
+
+/**
+ * Creates a new initialized TLS connection state. A connection state has
+ * a read mode and a write mode.
+ *
+ * compression state:
+ *   The current state of the compression algorithm.
+ *
+ * cipher state:
+ *   The current state of the encryption algorithm. This will consist of the
+ *   scheduled key for that connection. For stream ciphers, this will also
+ *   contain whatever state information is necessary to allow the stream to
+ *   continue to encrypt or decrypt data.
+ *
+ * MAC key:
+ *   The MAC key for the connection.
+ *
+ * sequence number:
+ *   Each connection state contains a sequence number, which is maintained
+ *   separately for read and write states. The sequence number MUST be set to
+ *   zero whenever a connection state is made the active state. Sequence
+ *   numbers are of type uint64 and may not exceed 2^64-1. Sequence numbers do
+ *   not wrap. If a TLS implementation would need to wrap a sequence number,
+ *   it must renegotiate instead. A sequence number is incremented after each
+ *   record: specifically, the first record transmitted under a particular
+ *   connection state MUST use sequence number 0.
+ *
+ * @param c the connection.
+ *
+ * @return the new initialized TLS connection state.
+ */
+tls.createConnectionState = function(c) {
+  var client = (c.entity === tls.ConnectionEnd.client);
+
+  var createMode = function() {
+    var mode = {
+      // two 32-bit numbers, first is most significant
+      sequenceNumber: [0, 0],
+      macKey: null,
+      macLength: 0,
+      macFunction: null,
+      cipherState: null,
+      cipherFunction: function(record) {return true;},
+      compressionState: null,
+      compressFunction: function(record) {return true;},
+      updateSequenceNumber: function() {
+        if(mode.sequenceNumber[1] === 0xFFFFFFFF) {
+          mode.sequenceNumber[1] = 0;
+          ++mode.sequenceNumber[0];
+        } else {
+          ++mode.sequenceNumber[1];
+        }
+      }
+    };
+    return mode;
+  };
+  var state = {
+    read: createMode(),
+    write: createMode()
+  };
+
+  // update function in read mode will decrypt then decompress a record
+  state.read.update = function(c, record) {
+    if(!state.read.cipherFunction(record, state.read)) {
+      c.error(c, {
+        message: 'Could not decrypt record or bad MAC.',
+        send: true,
+        alert: {
+          level: tls.Alert.Level.fatal,
+          // doesn't matter if decryption failed or MAC was
+          // invalid, return the same error so as not to reveal
+          // which one occurred
+          description: tls.Alert.Description.bad_record_mac
+        }
+      });
+    } else if(!state.read.compressFunction(c, record, state.read)) {
+      c.error(c, {
+        message: 'Could not decompress record.',
+        send: true,
+        alert: {
+          level: tls.Alert.Level.fatal,
+          description: tls.Alert.Description.decompression_failure
+        }
+      });
+    }
+    return !c.fail;
+  };
+
+  // update function in write mode will compress then encrypt a record
+  state.write.update = function(c, record) {
+    if(!state.write.compressFunction(c, record, state.write)) {
+      // error, but do not send alert since it would require
+      // compression as well
+      c.error(c, {
+        message: 'Could not compress record.',
+        send: false,
+        alert: {
+          level: tls.Alert.Level.fatal,
+          description: tls.Alert.Description.internal_error
+        }
+      });
+    } else if(!state.write.cipherFunction(record, state.write)) {
+      // error, but do not send alert since it would require
+      // encryption as well
+      c.error(c, {
+        message: 'Could not encrypt record.',
+        send: false,
+        alert: {
+          level: tls.Alert.Level.fatal,
+          description: tls.Alert.Description.internal_error
+        }
+      });
+    }
+    return !c.fail;
+  };
+
+  // handle security parameters
+  if(c.session) {
+    var sp = c.session.sp;
+    c.session.cipherSuite.initSecurityParameters(sp);
+
+    // generate keys
+    sp.keys = tls.generateKeys(c, sp);
+    state.read.macKey = client ?
+      sp.keys.server_write_MAC_key : sp.keys.client_write_MAC_key;
+    state.write.macKey = client ?
+      sp.keys.client_write_MAC_key : sp.keys.server_write_MAC_key;
+
+    // cipher suite setup
+    c.session.cipherSuite.initConnectionState(state, c, sp);
+
+    // compression setup
+    switch(sp.compression_algorithm) {
+    case tls.CompressionMethod.none:
+      break;
+    case tls.CompressionMethod.deflate:
+      state.read.compressFunction = inflate;
+      state.write.compressFunction = deflate;
+      break;
+    default:
+      throw new Error('Unsupported compression algorithm.');
+    }
+  }
+
+  return state;
+};
+
+/**
+ * Creates a Random structure.
+ *
+ * struct {
+ *   uint32 gmt_unix_time;
+ *   opaque random_bytes[28];
+ * } Random;
+ *
+ * gmt_unix_time:
+ *   The current time and date in standard UNIX 32-bit format (seconds since
+ *   the midnight starting Jan 1, 1970, UTC, ignoring leap seconds) according
+ *   to the sender's internal clock. Clocks are not required to be set
+ *   correctly by the basic TLS protocol; higher-level or application
+ *   protocols may define additional requirements. Note that, for historical
+ *   reasons, the data element is named using GMT, the predecessor of the
+ *   current worldwide time base, UTC.
+ * random_bytes:
+ *   28 bytes generated by a secure random number generator.
+ *
+ * @return the Random structure as a byte array.
+ */
+tls.createRandom = function() {
+  // get UTC milliseconds
+  var d = new Date();
+  var utc = +d + d.getTimezoneOffset() * 60000;
+  var rval = forge.util.createBuffer();
+  rval.putInt32(utc);
+  rval.putBytes(forge.random.getBytes(28));
+  return rval;
+};
+
+/**
+ * Creates a TLS record with the given type and data.
+ *
+ * @param c the connection.
+ * @param options:
+ *   type: the record type.
+ *   data: the plain text data in a byte buffer.
+ *
+ * @return the created record.
+ */
+tls.createRecord = function(c, options) {
+  if(!options.data) {
+    return null;
+  }
+  var record = {
+    type: options.type,
+    version: {
+      major: c.version.major,
+      minor: c.version.minor
+    },
+    length: options.data.length(),
+    fragment: options.data
+  };
+  return record;
+};
+
+/**
+ * Creates a TLS alert record.
+ *
+ * @param c the connection.
+ * @param alert:
+ *   level: the TLS alert level.
+ *   description: the TLS alert description.
+ *
+ * @return the created alert record.
+ */
+tls.createAlert = function(c, alert) {
+  var b = forge.util.createBuffer();
+  b.putByte(alert.level);
+  b.putByte(alert.description);
+  return tls.createRecord(c, {
+    type: tls.ContentType.alert,
+    data: b
+  });
+};
+
+/* The structure of a TLS handshake message.
+ *
+ * struct {
+ *    HandshakeType msg_type;    // handshake type
+ *    uint24 length;             // bytes in message
+ *    select(HandshakeType) {
+ *       case hello_request:       HelloRequest;
+ *       case client_hello:        ClientHello;
+ *       case server_hello:        ServerHello;
+ *       case certificate:         Certificate;
+ *       case server_key_exchange: ServerKeyExchange;
+ *       case certificate_request: CertificateRequest;
+ *       case server_hello_done:   ServerHelloDone;
+ *       case certificate_verify:  CertificateVerify;
+ *       case client_key_exchange: ClientKeyExchange;
+ *       case finished:            Finished;
+ *    } body;
+ * } Handshake;
+ */
+
+/**
+ * Creates a ClientHello message.
+ *
+ * opaque SessionID<0..32>;
+ * enum { null(0), deflate(1), (255) } CompressionMethod;
+ * uint8 CipherSuite[2];
+ *
+ * struct {
+ *   ProtocolVersion client_version;
+ *   Random random;
+ *   SessionID session_id;
+ *   CipherSuite cipher_suites<2..2^16-2>;
+ *   CompressionMethod compression_methods<1..2^8-1>;
+ *   select(extensions_present) {
+ *     case false:
+ *       struct {};
+ *     case true:
+ *       Extension extensions<0..2^16-1>;
+ *   };
+ * } ClientHello;
+ *
+ * The extension format for extended client hellos and server hellos is:
+ *
+ * struct {
+ *   ExtensionType extension_type;
+ *   opaque extension_data<0..2^16-1>;
+ * } Extension;
+ *
+ * Here:
+ *
+ * - "extension_type" identifies the particular extension type.
+ * - "extension_data" contains information specific to the particular
+ * extension type.
+ *
+ * The extension types defined in this document are:
+ *
+ * enum {
+ *   server_name(0), max_fragment_length(1),
+ *   client_certificate_url(2), trusted_ca_keys(3),
+ *   truncated_hmac(4), status_request(5), (65535)
+ * } ExtensionType;
+ *
+ * @param c the connection.
+ *
+ * @return the ClientHello byte buffer.
+ */
+tls.createClientHello = function(c) {
+  // save hello version
+  c.session.clientHelloVersion = {
+    major: c.version.major,
+    minor: c.version.minor
+  };
+
+  // create supported cipher suites
+  var cipherSuites = forge.util.createBuffer();
+  for(var i = 0; i < c.cipherSuites.length; ++i) {
+    var cs = c.cipherSuites[i];
+    cipherSuites.putByte(cs.id[0]);
+    cipherSuites.putByte(cs.id[1]);
+  }
+  var cSuites = cipherSuites.length();
+
+  // create supported compression methods, null always supported, but
+  // also support deflate if connection has inflate and deflate methods
+  var compressionMethods = forge.util.createBuffer();
+  compressionMethods.putByte(tls.CompressionMethod.none);
+  // FIXME: deflate support disabled until issues with raw deflate data
+  // without zlib headers are resolved
+  /*
+  if(c.inflate !== null && c.deflate !== null) {
+    compressionMethods.putByte(tls.CompressionMethod.deflate);
+  }
+  */
+  var cMethods = compressionMethods.length();
+
+  // create TLS SNI (server name indication) extension if virtual host
+  // has been specified, see RFC 3546
+  var extensions = forge.util.createBuffer();
+  if(c.virtualHost) {
+    // create extension struct
+    var ext = forge.util.createBuffer();
+    ext.putByte(0x00); // type server_name (ExtensionType is 2 bytes)
+    ext.putByte(0x00);
+
+    /* In order to provide the server name, clients MAY include an
+     * extension of type "server_name" in the (extended) client hello.
+     * The "extension_data" field of this extension SHALL contain
+     * "ServerNameList" where:
+     *
+     * struct {
+     *   NameType name_type;
+     *   select(name_type) {
+     *     case host_name: HostName;
+     *   } name;
+     * } ServerName;
+     *
+     * enum {
+     *   host_name(0), (255)
+     * } NameType;
+     *
+     * opaque HostName<1..2^16-1>;
+     *
+     * struct {
+     *   ServerName server_name_list<1..2^16-1>
+     * } ServerNameList;
+     */
+    var serverName = forge.util.createBuffer();
+    serverName.putByte(0x00); // type host_name
+    writeVector(serverName, 2, forge.util.createBuffer(c.virtualHost));
+
+    // ServerNameList is in extension_data
+    var snList = forge.util.createBuffer();
+    writeVector(snList, 2, serverName);
+    writeVector(ext, 2, snList);
+    extensions.putBuffer(ext);
+  }
+  var extLength = extensions.length();
+  if(extLength > 0) {
+    // add extension vector length
+    extLength += 2;
+  }
+
+  // determine length of the handshake message
+  // cipher suites and compression methods size will need to be
+  // updated if more get added to the list
+  var sessionId = c.session.id;
+  var length =
+    sessionId.length + 1 + // session ID vector
+    2 +                    // version (major + minor)
+    4 + 28 +               // random time and random bytes
+    2 + cSuites +          // cipher suites vector
+    1 + cMethods +         // compression methods vector
+    extLength;             // extensions vector
+
+  // build record fragment
+  var rval = forge.util.createBuffer();
+  rval.putByte(tls.HandshakeType.client_hello);
+  rval.putInt24(length);                     // handshake length
+  rval.putByte(c.version.major);             // major version
+  rval.putByte(c.version.minor);             // minor version
+  rval.putBytes(c.session.sp.client_random); // random time + bytes
+  writeVector(rval, 1, forge.util.createBuffer(sessionId));
+  writeVector(rval, 2, cipherSuites);
+  writeVector(rval, 1, compressionMethods);
+  if(extLength > 0) {
+    writeVector(rval, 2, extensions);
+  }
+  return rval;
+};
+
+/**
+ * Creates a ServerHello message.
+ *
+ * @param c the connection.
+ *
+ * @return the ServerHello byte buffer.
+ */
+tls.createServerHello = function(c) {
+  // determine length of the handshake message
+  var sessionId = c.session.id;
+  var length =
+    sessionId.length + 1 + // session ID vector
+    2 +                    // version (major + minor)
+    4 + 28 +               // random time and random bytes
+    2 +                    // chosen cipher suite
+    1;                     // chosen compression method
+
+  // build record fragment
+  var rval = forge.util.createBuffer();
+  rval.putByte(tls.HandshakeType.server_hello);
+  rval.putInt24(length);                     // handshake length
+  rval.putByte(c.version.major);             // major version
+  rval.putByte(c.version.minor);             // minor version
+  rval.putBytes(c.session.sp.server_random); // random time + bytes
+  writeVector(rval, 1, forge.util.createBuffer(sessionId));
+  rval.putByte(c.session.cipherSuite.id[0]);
+  rval.putByte(c.session.cipherSuite.id[1]);
+  rval.putByte(c.session.compressionMethod);
+  return rval;
+};
+
+/**
+ * Creates a Certificate message.
+ *
+ * When this message will be sent:
+ *   This is the first message the client can send after receiving a server
+ *   hello done message and the first message the server can send after
+ *   sending a ServerHello. This client message is only sent if the server
+ *   requests a certificate. If no suitable certificate is available, the
+ *   client should send a certificate message containing no certificates. If
+ *   client authentication is required by the server for the handshake to
+ *   continue, it may respond with a fatal handshake failure alert.
+ *
+ * opaque ASN.1Cert<1..2^24-1>;
+ *
+ * struct {
+ *   ASN.1Cert certificate_list<0..2^24-1>;
+ * } Certificate;
+ *
+ * @param c the connection.
+ *
+ * @return the Certificate byte buffer.
+ */
+tls.createCertificate = function(c) {
+  // TODO: check certificate request to ensure types are supported
+
+  // get a certificate (a certificate as a PEM string)
+  var client = (c.entity === tls.ConnectionEnd.client);
+  var cert = null;
+  if(c.getCertificate) {
+    var hint;
+    if(client) {
+      hint = c.session.certificateRequest;
+    } else {
+      hint = c.session.extensions.server_name.serverNameList;
+    }
+    cert = c.getCertificate(c, hint);
+  }
+
+  // buffer to hold certificate list
+  var certList = forge.util.createBuffer();
+  if(cert !== null) {
+    try {
+      // normalize cert to a chain of certificates
+      if(!forge.util.isArray(cert)) {
+        cert = [cert];
+      }
+      var asn1 = null;
+      for(var i = 0; i < cert.length; ++i) {
+        var msg = forge.pem.decode(cert[i])[0];
+        if(msg.type !== 'CERTIFICATE' &&
+          msg.type !== 'X509 CERTIFICATE' &&
+          msg.type !== 'TRUSTED CERTIFICATE') {
+          var error = new Error('Could not convert certificate from PEM; PEM ' +
+            'header type is not "CERTIFICATE", "X509 CERTIFICATE", or ' +
+            '"TRUSTED CERTIFICATE".');
+          error.headerType = msg.type;
+          throw error;
+        }
+        if(msg.procType && msg.procType.type === 'ENCRYPTED') {
+          throw new Error('Could not convert certificate from PEM; PEM is encrypted.');
+        }
+
+        var der = forge.util.createBuffer(msg.body);
+        if(asn1 === null) {
+          asn1 = forge.asn1.fromDer(der.bytes(), false);
+        }
+
+        // certificate entry is itself a vector with 3 length bytes
+        var certBuffer = forge.util.createBuffer();
+        writeVector(certBuffer, 3, der);
+
+        // add cert vector to cert list vector
+        certList.putBuffer(certBuffer);
+      }
+
+      // save certificate
+      cert = forge.pki.certificateFromAsn1(asn1);
+      if(client) {
+        c.session.clientCertificate = cert;
+      } else {
+        c.session.serverCertificate = cert;
+      }
+    } catch(ex) {
+      return c.error(c, {
+        message: 'Could not send certificate list.',
+        cause: ex,
+        send: true,
+        alert: {
+          level: tls.Alert.Level.fatal,
+          description: tls.Alert.Description.bad_certificate
+        }
+      });
+    }
+  }
+
+  // determine length of the handshake message
+  var length = 3 + certList.length(); // cert list vector
+
+  // build record fragment
+  var rval = forge.util.createBuffer();
+  rval.putByte(tls.HandshakeType.certificate);
+  rval.putInt24(length);
+  writeVector(rval, 3, certList);
+  return rval;
+};
+
+/**
+ * Creates a ClientKeyExchange message.
+ *
+ * When this message will be sent:
+ *   This message is always sent by the client. It will immediately follow the
+ *   client certificate message, if it is sent. Otherwise it will be the first
+ *   message sent by the client after it receives the server hello done
+ *   message.
+ *
+ * Meaning of this message:
+ *   With this message, the premaster secret is set, either though direct
+ *   transmission of the RSA-encrypted secret, or by the transmission of
+ *   Diffie-Hellman parameters which will allow each side to agree upon the
+ *   same premaster secret. When the key exchange method is DH_RSA or DH_DSS,
+ *   client certification has been requested, and the client was able to
+ *   respond with a certificate which contained a Diffie-Hellman public key
+ *   whose parameters (group and generator) matched those specified by the
+ *   server in its certificate, this message will not contain any data.
+ *
+ * Meaning of this message:
+ *   If RSA is being used for key agreement and authentication, the client
+ *   generates a 48-byte premaster secret, encrypts it using the public key
+ *   from the server's certificate or the temporary RSA key provided in a
+ *   server key exchange message, and sends the result in an encrypted
+ *   premaster secret message. This structure is a variant of the client
+ *   key exchange message, not a message in itself.
+ *
+ * struct {
+ *   select(KeyExchangeAlgorithm) {
+ *     case rsa: EncryptedPreMasterSecret;
+ *     case diffie_hellman: ClientDiffieHellmanPublic;
+ *   } exchange_keys;
+ * } ClientKeyExchange;
+ *
+ * struct {
+ *   ProtocolVersion client_version;
+ *   opaque random[46];
+ * } PreMasterSecret;
+ *
+ * struct {
+ *   public-key-encrypted PreMasterSecret pre_master_secret;
+ * } EncryptedPreMasterSecret;
+ *
+ * A public-key-encrypted element is encoded as a vector <0..2^16-1>.
+ *
+ * @param c the connection.
+ *
+ * @return the ClientKeyExchange byte buffer.
+ */
+tls.createClientKeyExchange = function(c) {
+  // create buffer to encrypt
+  var b = forge.util.createBuffer();
+
+  // add highest client-supported protocol to help server avoid version
+  // rollback attacks
+  b.putByte(c.session.clientHelloVersion.major);
+  b.putByte(c.session.clientHelloVersion.minor);
+
+  // generate and add 46 random bytes
+  b.putBytes(forge.random.getBytes(46));
+
+  // save pre-master secret
+  var sp = c.session.sp;
+  sp.pre_master_secret = b.getBytes();
+
+  // RSA-encrypt the pre-master secret
+  var key = c.session.serverCertificate.publicKey;
+  b = key.encrypt(sp.pre_master_secret);
+
+  /* Note: The encrypted pre-master secret will be stored in a
+    public-key-encrypted opaque vector that has the length prefixed using
+    2 bytes, so include those 2 bytes in the handshake message length. This
+    is done as a minor optimization instead of calling writeVector(). */
+
+  // determine length of the handshake message
+  var length = b.length + 2;
+
+  // build record fragment
+  var rval = forge.util.createBuffer();
+  rval.putByte(tls.HandshakeType.client_key_exchange);
+  rval.putInt24(length);
+  // add vector length bytes
+  rval.putInt16(b.length);
+  rval.putBytes(b);
+  return rval;
+};
+
+/**
+ * Creates a ServerKeyExchange message.
+ *
+ * @param c the connection.
+ *
+ * @return the ServerKeyExchange byte buffer.
+ */
+tls.createServerKeyExchange = function(c) {
+  // this implementation only supports RSA, no Diffie-Hellman support,
+  // so this record is empty
+
+  // determine length of the handshake message
+  var length = 0;
+
+  // build record fragment
+  var rval = forge.util.createBuffer();
+  if(length > 0) {
+    rval.putByte(tls.HandshakeType.server_key_exchange);
+    rval.putInt24(length);
+  }
+  return rval;
+};
+
+/**
+ * Gets the signed data used to verify a client-side certificate. See
+ * tls.createCertificateVerify() for details.
+ *
+ * @param c the connection.
+ * @param callback the callback to call once the signed data is ready.
+ */
+tls.getClientSignature = function(c, callback) {
+  // generate data to RSA encrypt
+  var b = forge.util.createBuffer();
+  b.putBuffer(c.session.md5.digest());
+  b.putBuffer(c.session.sha1.digest());
+  b = b.getBytes();
+
+  // create default signing function as necessary
+  c.getSignature = c.getSignature || function(c, b, callback) {
+    // do rsa encryption, call callback
+    var privateKey = null;
+    if(c.getPrivateKey) {
+      try {
+        privateKey = c.getPrivateKey(c, c.session.clientCertificate);
+        privateKey = forge.pki.privateKeyFromPem(privateKey);
+      } catch(ex) {
+        c.error(c, {
+          message: 'Could not get private key.',
+          cause: ex,
+          send: true,
+          alert: {
+            level: tls.Alert.Level.fatal,
+            description: tls.Alert.Description.internal_error
+          }
+        });
+      }
+    }
+    if(privateKey === null) {
+      c.error(c, {
+        message: 'No private key set.',
+        send: true,
+        alert: {
+          level: tls.Alert.Level.fatal,
+          description: tls.Alert.Description.internal_error
+        }
+      });
+    } else {
+      b = privateKey.sign(b, null);
+    }
+    callback(c, b);
+  };
+
+  // get client signature
+  c.getSignature(c, b, callback);
+};
+
+/**
+ * Creates a CertificateVerify message.
+ *
+ * Meaning of this message:
+ *   This structure conveys the client's Diffie-Hellman public value
+ *   (Yc) if it was not already included in the client's certificate.
+ *   The encoding used for Yc is determined by the enumerated
+ *   PublicValueEncoding. This structure is a variant of the client
+ *   key exchange message, not a message in itself.
+ *
+ * When this message will be sent:
+ *   This message is used to provide explicit verification of a client
+ *   certificate. This message is only sent following a client
+ *   certificate that has signing capability (i.e. all certificates
+ *   except those containing fixed Diffie-Hellman parameters). When
+ *   sent, it will immediately follow the client key exchange message.
+ *
+ * struct {
+ *   Signature signature;
+ * } CertificateVerify;
+ *
+ * CertificateVerify.signature.md5_hash
+ *   MD5(handshake_messages);
+ *
+ * Certificate.signature.sha_hash
+ *   SHA(handshake_messages);
+ *
+ * Here handshake_messages refers to all handshake messages sent or
+ * received starting at client hello up to but not including this
+ * message, including the type and length fields of the handshake
+ * messages.
+ *
+ * select(SignatureAlgorithm) {
+ *   case anonymous: struct { };
+ *   case rsa:
+ *     digitally-signed struct {
+ *       opaque md5_hash[16];
+ *       opaque sha_hash[20];
+ *     };
+ *   case dsa:
+ *     digitally-signed struct {
+ *       opaque sha_hash[20];
+ *     };
+ * } Signature;
+ *
+ * In digital signing, one-way hash functions are used as input for a
+ * signing algorithm. A digitally-signed element is encoded as an opaque
+ * vector <0..2^16-1>, where the length is specified by the signing
+ * algorithm and key.
+ *
+ * In RSA signing, a 36-byte structure of two hashes (one SHA and one
+ * MD5) is signed (encrypted with the private key). It is encoded with
+ * PKCS #1 block type 0 or type 1 as described in [PKCS1].
+ *
+ * In DSS, the 20 bytes of the SHA hash are run directly through the
+ * Digital Signing Algorithm with no additional hashing.
+ *
+ * @param c the connection.
+ * @param signature the signature to include in the message.
+ *
+ * @return the CertificateVerify byte buffer.
+ */
+tls.createCertificateVerify = function(c, signature) {
+  /* Note: The signature will be stored in a "digitally-signed" opaque
+    vector that has the length prefixed using 2 bytes, so include those
+    2 bytes in the handshake message length. This is done as a minor
+    optimization instead of calling writeVector(). */
+
+  // determine length of the handshake message
+  var length = signature.length + 2;
+
+  // build record fragment
+  var rval = forge.util.createBuffer();
+  rval.putByte(tls.HandshakeType.certificate_verify);
+  rval.putInt24(length);
+  // add vector length bytes
+  rval.putInt16(signature.length);
+  rval.putBytes(signature);
+  return rval;
+};
+
+/**
+ * Creates a CertificateRequest message.
+ *
+ * @param c the connection.
+ *
+ * @return the CertificateRequest byte buffer.
+ */
+tls.createCertificateRequest = function(c) {
+  // TODO: support other certificate types
+  var certTypes = forge.util.createBuffer();
+
+  // common RSA certificate type
+  certTypes.putByte(0x01);
+
+  // add distinguished names from CA store
+  var cAs = forge.util.createBuffer();
+  for(var key in c.caStore.certs) {
+    var cert = c.caStore.certs[key];
+    var dn = forge.pki.distinguishedNameToAsn1(cert.subject);
+    var byteBuffer = forge.asn1.toDer(dn);
+    cAs.putInt16(byteBuffer.length());
+    cAs.putBuffer(byteBuffer);
+  }
+
+  // TODO: TLS 1.2+ has a different format
+
+  // determine length of the handshake message
+  var length =
+    1 + certTypes.length() +
+    2 + cAs.length();
+
+  // build record fragment
+  var rval = forge.util.createBuffer();
+  rval.putByte(tls.HandshakeType.certificate_request);
+  rval.putInt24(length);
+  writeVector(rval, 1, certTypes);
+  writeVector(rval, 2, cAs);
+  return rval;
+};
+
+/**
+ * Creates a ServerHelloDone message.
+ *
+ * @param c the connection.
+ *
+ * @return the ServerHelloDone byte buffer.
+ */
+tls.createServerHelloDone = function(c) {
+  // build record fragment
+  var rval = forge.util.createBuffer();
+  rval.putByte(tls.HandshakeType.server_hello_done);
+  rval.putInt24(0);
+  return rval;
+};
+
+/**
+ * Creates a ChangeCipherSpec message.
+ *
+ * The change cipher spec protocol exists to signal transitions in
+ * ciphering strategies. The protocol consists of a single message,
+ * which is encrypted and compressed under the current (not the pending)
+ * connection state. The message consists of a single byte of value 1.
+ *
+ * struct {
+ *   enum { change_cipher_spec(1), (255) } type;
+ * } ChangeCipherSpec;
+ *
+ * @return the ChangeCipherSpec byte buffer.
+ */
+tls.createChangeCipherSpec = function() {
+  var rval = forge.util.createBuffer();
+  rval.putByte(0x01);
+  return rval;
+};
+
+/**
+ * Creates a Finished message.
+ *
+ * struct {
+ *   opaque verify_data[12];
+ * } Finished;
+ *
+ * verify_data
+ *   PRF(master_secret, finished_label, MD5(handshake_messages) +
+ *   SHA-1(handshake_messages)) [0..11];
+ *
+ * finished_label
+ *   For Finished messages sent by the client, the string "client
+ *   finished". For Finished messages sent by the server, the
+ *   string "server finished".
+ *
+ * handshake_messages
+ *   All of the data from all handshake messages up to but not
+ *   including this message. This is only data visible at the
+ *   handshake layer and does not include record layer headers.
+ *   This is the concatenation of all the Handshake structures as
+ *   defined in 7.4 exchanged thus far.
+ *
+ * @param c the connection.
+ *
+ * @return the Finished byte buffer.
+ */
+tls.createFinished = function(c) {
+  // generate verify_data
+  var b = forge.util.createBuffer();
+  b.putBuffer(c.session.md5.digest());
+  b.putBuffer(c.session.sha1.digest());
+
+  // TODO: determine prf function and verify length for TLS 1.2
+  var client = (c.entity === tls.ConnectionEnd.client);
+  var sp = c.session.sp;
+  var vdl = 12;
+  var prf = prf_TLS1;
+  var label = client ? 'client finished' : 'server finished';
+  b = prf(sp.master_secret, label, b.getBytes(), vdl);
+
+  // build record fragment
+  var rval = forge.util.createBuffer();
+  rval.putByte(tls.HandshakeType.finished);
+  rval.putInt24(b.length());
+  rval.putBuffer(b);
+  return rval;
+};
+
+/**
+ * Creates a HeartbeatMessage (See RFC 6520).
+ *
+ * struct {
+ *   HeartbeatMessageType type;
+ *   uint16 payload_length;
+ *   opaque payload[HeartbeatMessage.payload_length];
+ *   opaque padding[padding_length];
+ * } HeartbeatMessage;
+ *
+ * The total length of a HeartbeatMessage MUST NOT exceed 2^14 or
+ * max_fragment_length when negotiated as defined in [RFC6066].
+ *
+ * type: The message type, either heartbeat_request or heartbeat_response.
+ *
+ * payload_length: The length of the payload.
+ *
+ * payload: The payload consists of arbitrary content.
+ *
+ * padding: The padding is random content that MUST be ignored by the
+ *   receiver. The length of a HeartbeatMessage is TLSPlaintext.length
+ *   for TLS and DTLSPlaintext.length for DTLS. Furthermore, the
+ *   length of the type field is 1 byte, and the length of the
+ *   payload_length is 2. Therefore, the padding_length is
+ *   TLSPlaintext.length - payload_length - 3 for TLS and
+ *   DTLSPlaintext.length - payload_length - 3 for DTLS. The
+ *   padding_length MUST be at least 16.
+ *
+ * The sender of a HeartbeatMessage MUST use a random padding of at
+ * least 16 bytes. The padding of a received HeartbeatMessage message
+ * MUST be ignored.
+ *
+ * If the payload_length of a received HeartbeatMessage is too large,
+ * the received HeartbeatMessage MUST be discarded silently.
+ *
+ * @param c the connection.
+ * @param type the tls.HeartbeatMessageType.
+ * @param payload the heartbeat data to send as the payload.
+ * @param [payloadLength] the payload length to use, defaults to the
+ *          actual payload length.
+ *
+ * @return the HeartbeatRequest byte buffer.
+ */
+tls.createHeartbeat = function(type, payload, payloadLength) {
+  if(typeof payloadLength === 'undefined') {
+    payloadLength = payload.length;
+  }
+  // build record fragment
+  var rval = forge.util.createBuffer();
+  rval.putByte(type);               // heartbeat message type
+  rval.putInt16(payloadLength);     // payload length
+  rval.putBytes(payload);           // payload
+  // padding
+  var plaintextLength = rval.length();
+  var paddingLength = Math.max(16, plaintextLength - payloadLength - 3);
+  rval.putBytes(forge.random.getBytes(paddingLength));
+  return rval;
+};
+
+/**
+ * Fragments, compresses, encrypts, and queues a record for delivery.
+ *
+ * @param c the connection.
+ * @param record the record to queue.
+ */
+tls.queue = function(c, record) {
+  // error during record creation
+  if(!record) {
+    return;
+  }
+
+  if(record.fragment.length() === 0) {
+    if(record.type === tls.ContentType.handshake ||
+      record.type === tls.ContentType.alert ||
+      record.type === tls.ContentType.change_cipher_spec) {
+      // Empty handshake, alert of change cipher spec messages are not allowed per the TLS specification and should not be sent.
+      return;
+    }
+  }
+
+  // if the record is a handshake record, update handshake hashes
+  if(record.type === tls.ContentType.handshake) {
+    var bytes = record.fragment.bytes();
+    c.session.md5.update(bytes);
+    c.session.sha1.update(bytes);
+    bytes = null;
+  }
+
+  // handle record fragmentation
+  var records;
+  if(record.fragment.length() <= tls.MaxFragment) {
+    records = [record];
+  } else {
+    // fragment data as long as it is too long
+    records = [];
+    var data = record.fragment.bytes();
+    while(data.length > tls.MaxFragment) {
+      records.push(tls.createRecord(c, {
+        type: record.type,
+        data: forge.util.createBuffer(data.slice(0, tls.MaxFragment))
+      }));
+      data = data.slice(tls.MaxFragment);
+    }
+    // add last record
+    if(data.length > 0) {
+      records.push(tls.createRecord(c, {
+        type: record.type,
+        data: forge.util.createBuffer(data)
+      }));
+    }
+  }
+
+  // compress and encrypt all fragmented records
+  for(var i = 0; i < records.length && !c.fail; ++i) {
+    // update the record using current write state
+    var rec = records[i];
+    var s = c.state.current.write;
+    if(s.update(c, rec)) {
+      // store record
+      c.records.push(rec);
+    }
+  }
+};
+
+/**
+ * Flushes all queued records to the output buffer and calls the
+ * tlsDataReady() handler on the given connection.
+ *
+ * @param c the connection.
+ *
+ * @return true on success, false on failure.
+ */
+tls.flush = function(c) {
+  for(var i = 0; i < c.records.length; ++i) {
+    var record = c.records[i];
+
+    // add record header and fragment
+    c.tlsData.putByte(record.type);
+    c.tlsData.putByte(record.version.major);
+    c.tlsData.putByte(record.version.minor);
+    c.tlsData.putInt16(record.fragment.length());
+    c.tlsData.putBuffer(c.records[i].fragment);
+  }
+  c.records = [];
+  return c.tlsDataReady(c);
+};
+
+/**
+ * Maps a pki.certificateError to a tls.Alert.Description.
+ *
+ * @param error the error to map.
+ *
+ * @return the alert description.
+ */
+var _certErrorToAlertDesc = function(error) {
+  switch(error) {
+  case true:
+    return true;
+  case forge.pki.certificateError.bad_certificate:
+    return tls.Alert.Description.bad_certificate;
+  case forge.pki.certificateError.unsupported_certificate:
+    return tls.Alert.Description.unsupported_certificate;
+  case forge.pki.certificateError.certificate_revoked:
+    return tls.Alert.Description.certificate_revoked;
+  case forge.pki.certificateError.certificate_expired:
+    return tls.Alert.Description.certificate_expired;
+  case forge.pki.certificateError.certificate_unknown:
+    return tls.Alert.Description.certificate_unknown;
+  case forge.pki.certificateError.unknown_ca:
+    return tls.Alert.Description.unknown_ca;
+  default:
+    return tls.Alert.Description.bad_certificate;
+  }
+};
+
+/**
+ * Maps a tls.Alert.Description to a pki.certificateError.
+ *
+ * @param desc the alert description.
+ *
+ * @return the certificate error.
+ */
+var _alertDescToCertError = function(desc) {
+  switch(desc) {
+  case true:
+    return true;
+  case tls.Alert.Description.bad_certificate:
+    return forge.pki.certificateError.bad_certificate;
+  case tls.Alert.Description.unsupported_certificate:
+    return forge.pki.certificateError.unsupported_certificate;
+  case tls.Alert.Description.certificate_revoked:
+    return forge.pki.certificateError.certificate_revoked;
+  case tls.Alert.Description.certificate_expired:
+    return forge.pki.certificateError.certificate_expired;
+  case tls.Alert.Description.certificate_unknown:
+    return forge.pki.certificateError.certificate_unknown;
+  case tls.Alert.Description.unknown_ca:
+    return forge.pki.certificateError.unknown_ca;
+  default:
+    return forge.pki.certificateError.bad_certificate;
+  }
+};
+
+/**
+ * Verifies a certificate chain against the given connection's
+ * Certificate Authority store.
+ *
+ * @param c the TLS connection.
+ * @param chain the certificate chain to verify, with the root or highest
+ *          authority at the end.
+ *
+ * @return true if successful, false if not.
+ */
+tls.verifyCertificateChain = function(c, chain) {
+  try {
+    // Make a copy of c.verifyOptions so that we can modify options.verify
+    // without modifying c.verifyOptions.
+    var options = {};
+    for (var key in c.verifyOptions) {
+      options[key] = c.verifyOptions[key];
+    }
+
+    options.verify = function(vfd, depth, chain) {
+      // convert pki.certificateError to tls alert description
+      var desc = _certErrorToAlertDesc(vfd);
+
+      // call application callback
+      var ret = c.verify(c, vfd, depth, chain);
+      if(ret !== true) {
+        if(typeof ret === 'object' && !forge.util.isArray(ret)) {
+          // throw custom error
+          var error = new Error('The application rejected the certificate.');
+          error.send = true;
+          error.alert = {
+            level: tls.Alert.Level.fatal,
+            description: tls.Alert.Description.bad_certificate
+          };
+          if(ret.message) {
+            error.message = ret.message;
+          }
+          if(ret.alert) {
+            error.alert.description = ret.alert;
+          }
+          throw error;
+        }
+
+        // convert tls alert description to pki.certificateError
+        if(ret !== vfd) {
+          ret = _alertDescToCertError(ret);
+        }
+      }
+
+      return ret;
+    };
+
+    // verify chain
+    forge.pki.verifyCertificateChain(c.caStore, chain, options);
+  } catch(ex) {
+    // build tls error if not already customized
+    var err = ex;
+    if(typeof err !== 'object' || forge.util.isArray(err)) {
+      err = {
+        send: true,
+        alert: {
+          level: tls.Alert.Level.fatal,
+          description: _certErrorToAlertDesc(ex)
+        }
+      };
+    }
+    if(!('send' in err)) {
+      err.send = true;
+    }
+    if(!('alert' in err)) {
+      err.alert = {
+        level: tls.Alert.Level.fatal,
+        description: _certErrorToAlertDesc(err.error)
+      };
+    }
+
+    // send error
+    c.error(c, err);
+  }
+
+  return !c.fail;
+};
+
+/**
+ * Creates a new TLS session cache.
+ *
+ * @param cache optional map of session ID to cached session.
+ * @param capacity the maximum size for the cache (default: 100).
+ *
+ * @return the new TLS session cache.
+ */
+tls.createSessionCache = function(cache, capacity) {
+  var rval = null;
+
+  // assume input is already a session cache object
+  if(cache && cache.getSession && cache.setSession && cache.order) {
+    rval = cache;
+  } else {
+    // create cache
+    rval = {};
+    rval.cache = cache || {};
+    rval.capacity = Math.max(capacity || 100, 1);
+    rval.order = [];
+
+    // store order for sessions, delete session overflow
+    for(var key in cache) {
+      if(rval.order.length <= capacity) {
+        rval.order.push(key);
+      } else {
+        delete cache[key];
+      }
+    }
+
+    // get a session from a session ID (or get any session)
+    rval.getSession = function(sessionId) {
+      var session = null;
+      var key = null;
+
+      // if session ID provided, use it
+      if(sessionId) {
+        key = forge.util.bytesToHex(sessionId);
+      } else if(rval.order.length > 0) {
+        // get first session from cache
+        key = rval.order[0];
+      }
+
+      if(key !== null && key in rval.cache) {
+        // get cached session and remove from cache
+        session = rval.cache[key];
+        delete rval.cache[key];
+        for(var i in rval.order) {
+          if(rval.order[i] === key) {
+            rval.order.splice(i, 1);
+            break;
+          }
+        }
+      }
+
+      return session;
+    };
+
+    // set a session in the cache
+    rval.setSession = function(sessionId, session) {
+      // remove session from cache if at capacity
+      if(rval.order.length === rval.capacity) {
+        var key = rval.order.shift();
+        delete rval.cache[key];
+      }
+      // add session to cache
+      var key = forge.util.bytesToHex(sessionId);
+      rval.order.push(key);
+      rval.cache[key] = session;
+    };
+  }
+
+  return rval;
+};
+
+/**
+ * Creates a new TLS connection.
+ *
+ * See public createConnection() docs for more details.
+ *
+ * @param options the options for this connection.
+ *
+ * @return the new TLS connection.
+ */
+tls.createConnection = function(options) {
+  var caStore = null;
+  if(options.caStore) {
+    // if CA store is an array, convert it to a CA store object
+    if(forge.util.isArray(options.caStore)) {
+      caStore = forge.pki.createCaStore(options.caStore);
+    } else {
+      caStore = options.caStore;
+    }
+  } else {
+    // create empty CA store
+    caStore = forge.pki.createCaStore();
+  }
+
+  // setup default cipher suites
+  var cipherSuites = options.cipherSuites || null;
+  if(cipherSuites === null) {
+    cipherSuites = [];
+    for(var key in tls.CipherSuites) {
+      cipherSuites.push(tls.CipherSuites[key]);
+    }
+  }
+
+  // set default entity
+  var entity = (options.server || false) ?
+    tls.ConnectionEnd.server : tls.ConnectionEnd.client;
+
+  // create session cache if requested
+  var sessionCache = options.sessionCache ?
+    tls.createSessionCache(options.sessionCache) : null;
+
+  // create TLS connection
+  var c = {
+    version: {major: tls.Version.major, minor: tls.Version.minor},
+    entity: entity,
+    sessionId: options.sessionId,
+    caStore: caStore,
+    sessionCache: sessionCache,
+    cipherSuites: cipherSuites,
+    connected: options.connected,
+    virtualHost: options.virtualHost || null,
+    verifyClient: options.verifyClient || false,
+    verify: options.verify || function(cn, vfd, dpth, cts) {return vfd;},
+    verifyOptions: options.verifyOptions || {},
+    getCertificate: options.getCertificate || null,
+    getPrivateKey: options.getPrivateKey || null,
+    getSignature: options.getSignature || null,
+    input: forge.util.createBuffer(),
+    tlsData: forge.util.createBuffer(),
+    data: forge.util.createBuffer(),
+    tlsDataReady: options.tlsDataReady,
+    dataReady: options.dataReady,
+    heartbeatReceived: options.heartbeatReceived,
+    closed: options.closed,
+    error: function(c, ex) {
+      // set origin if not set
+      ex.origin = ex.origin ||
+        ((c.entity === tls.ConnectionEnd.client) ? 'client' : 'server');
+
+      // send TLS alert
+      if(ex.send) {
+        tls.queue(c, tls.createAlert(c, ex.alert));
+        tls.flush(c);
+      }
+
+      // error is fatal by default
+      var fatal = (ex.fatal !== false);
+      if(fatal) {
+        // set fail flag
+        c.fail = true;
+      }
+
+      // call error handler first
+      options.error(c, ex);
+
+      if(fatal) {
+        // fatal error, close connection, do not clear fail
+        c.close(false);
+      }
+    },
+    deflate: options.deflate || null,
+    inflate: options.inflate || null
+  };
+
+  /**
+   * Resets a closed TLS connection for reuse. Called in c.close().
+   *
+   * @param clearFail true to clear the fail flag (default: true).
+   */
+  c.reset = function(clearFail) {
+    c.version = {major: tls.Version.major, minor: tls.Version.minor};
+    c.record = null;
+    c.session = null;
+    c.peerCertificate = null;
+    c.state = {
+      pending: null,
+      current: null
+    };
+    c.expect = (c.entity === tls.ConnectionEnd.client) ? SHE : CHE;
+    c.fragmented = null;
+    c.records = [];
+    c.open = false;
+    c.handshakes = 0;
+    c.handshaking = false;
+    c.isConnected = false;
+    c.fail = !(clearFail || typeof(clearFail) === 'undefined');
+    c.input.clear();
+    c.tlsData.clear();
+    c.data.clear();
+    c.state.current = tls.createConnectionState(c);
+  };
+
+  // do initial reset of connection
+  c.reset();
+
+  /**
+   * Updates the current TLS engine state based on the given record.
+   *
+   * @param c the TLS connection.
+   * @param record the TLS record to act on.
+   */
+  var _update = function(c, record) {
+    // get record handler (align type in table by subtracting lowest)
+    var aligned = record.type - tls.ContentType.change_cipher_spec;
+    var handlers = ctTable[c.entity][c.expect];
+    if(aligned in handlers) {
+      handlers[aligned](c, record);
+    } else {
+      // unexpected record
+      tls.handleUnexpected(c, record);
+    }
+  };
+
+  /**
+   * Reads the record header and initializes the next record on the given
+   * connection.
+   *
+   * @param c the TLS connection with the next record.
+   *
+   * @return 0 if the input data could be processed, otherwise the
+   *         number of bytes required for data to be processed.
+   */
+  var _readRecordHeader = function(c) {
+    var rval = 0;
+
+    // get input buffer and its length
+    var b = c.input;
+    var len = b.length();
+
+    // need at least 5 bytes to initialize a record
+    if(len < 5) {
+      rval = 5 - len;
+    } else {
+      // enough bytes for header
+      // initialize record
+      c.record = {
+        type: b.getByte(),
+        version: {
+          major: b.getByte(),
+          minor: b.getByte()
+        },
+        length: b.getInt16(),
+        fragment: forge.util.createBuffer(),
+        ready: false
+      };
+
+      // check record version
+      var compatibleVersion = (c.record.version.major === c.version.major);
+      if(compatibleVersion && c.session && c.session.version) {
+        // session version already set, require same minor version
+        compatibleVersion = (c.record.version.minor === c.version.minor);
+      }
+      if(!compatibleVersion) {
+        c.error(c, {
+          message: 'Incompatible TLS version.',
+          send: true,
+          alert: {
+            level: tls.Alert.Level.fatal,
+            description: tls.Alert.Description.protocol_version
+          }
+        });
+      }
+    }
+
+    return rval;
+  };
+
+  /**
+   * Reads the next record's contents and appends its message to any
+   * previously fragmented message.
+   *
+   * @param c the TLS connection with the next record.
+   *
+   * @return 0 if the input data could be processed, otherwise the
+   *         number of bytes required for data to be processed.
+   */
+  var _readRecord = function(c) {
+    var rval = 0;
+
+    // ensure there is enough input data to get the entire record
+    var b = c.input;
+    var len = b.length();
+    if(len < c.record.length) {
+      // not enough data yet, return how much is required
+      rval = c.record.length - len;
+    } else {
+      // there is enough data to parse the pending record
+      // fill record fragment and compact input buffer
+      c.record.fragment.putBytes(b.getBytes(c.record.length));
+      b.compact();
+
+      // update record using current read state
+      var s = c.state.current.read;
+      if(s.update(c, c.record)) {
+        // see if there is a previously fragmented message that the
+        // new record's message fragment should be appended to
+        if(c.fragmented !== null) {
+          // if the record type matches a previously fragmented
+          // record, append the record fragment to it
+          if(c.fragmented.type === c.record.type) {
+            // concatenate record fragments
+            c.fragmented.fragment.putBuffer(c.record.fragment);
+            c.record = c.fragmented;
+          } else {
+            // error, invalid fragmented record
+            c.error(c, {
+              message: 'Invalid fragmented record.',
+              send: true,
+              alert: {
+                level: tls.Alert.Level.fatal,
+                description:
+                  tls.Alert.Description.unexpected_message
+              }
+            });
+            // fatal error closed and reset the connection (no record)
+            return rval;
+          }
+        }
+
+        // record is now ready
+        c.record.ready = true;
+      }
+    }
+
+    return rval;
+  };
+
+  /**
+   * Performs a handshake using the TLS Handshake Protocol, as a client.
+   *
+   * This method should only be called if the connection is in client mode.
+   *
+   * @param sessionId the session ID to use, null to start a new one.
+   */
+  c.handshake = function(sessionId) {
+    // error to call this in non-client mode
+    if(c.entity !== tls.ConnectionEnd.client) {
+      // not fatal error
+      c.error(c, {
+        message: 'Cannot initiate handshake as a server.',
+        fatal: false
+      });
+    } else if(c.handshaking) {
+      // handshake is already in progress, fail but not fatal error
+      c.error(c, {
+        message: 'Handshake already in progress.',
+        fatal: false
+      });
+    } else {
+      // clear fail flag on reuse
+      if(c.fail && !c.open && c.handshakes === 0) {
+        c.fail = false;
+      }
+
+      // now handshaking
+      c.handshaking = true;
+
+      // default to blank (new session)
+      sessionId = sessionId || '';
+
+      // if a session ID was specified, try to find it in the cache
+      var session = null;
+      if(sessionId.length > 0) {
+        if(c.sessionCache) {
+          session = c.sessionCache.getSession(sessionId);
+        }
+
+        // matching session not found in cache, clear session ID
+        if(session === null) {
+          sessionId = '';
+        }
+      }
+
+      // no session given, grab a session from the cache, if available
+      if(sessionId.length === 0 && c.sessionCache) {
+        session = c.sessionCache.getSession();
+        if(session !== null) {
+          sessionId = session.id;
+        }
+      }
+
+      // set up session
+      c.session = {
+        id: sessionId,
+        version: null,
+        cipherSuite: null,
+        compressionMethod: null,
+        serverCertificate: null,
+        certificateRequest: null,
+        clientCertificate: null,
+        sp: {},
+        md5: forge.md.md5.create(),
+        sha1: forge.md.sha1.create()
+      };
+
+      // use existing session information
+      if(session) {
+        // only update version on connection, session version not yet set
+        c.version = session.version;
+        c.session.sp = session.sp;
+      }
+
+      // generate new client random
+      c.session.sp.client_random = tls.createRandom().getBytes();
+
+      // connection now open
+      c.open = true;
+
+      // send hello
+      tls.queue(c, tls.createRecord(c, {
+        type: tls.ContentType.handshake,
+        data: tls.createClientHello(c)
+      }));
+      tls.flush(c);
+    }
+  };
+
+  // true while c.process() is handling records
+  var _processing = false;
+  // true when c.process() was called again while handling a record
+  var _processNext = false;
+
+  /**
+   * Reads the next record and, once it is complete, passes it to its
+   * handler. Handlers call c.process() to continue with the next record.
+   *
+   * @param c the TLS connection.
+   *
+   * @return 0 if the input data could be processed, otherwise the
+   *         number of bytes required for data to be processed.
+   */
+  var _processRecord = function(c) {
+    var rval = 0;
+
+    // process next record if no failure, process will be called after
+    // each record is handled (since handling can be asynchronous)
+    if(!c.fail) {
+      // reset record if ready and now empty
+      if(c.record !== null &&
+        c.record.ready && c.record.fragment.isEmpty()) {
+        c.record = null;
+      }
+
+      // if there is no pending record, try to read record header
+      if(c.record === null) {
+        rval = _readRecordHeader(c);
+      }
+
+      // read the next record (if record not yet ready)
+      if(!c.fail && c.record !== null && !c.record.ready) {
+        rval = _readRecord(c);
+      }
+
+      // record ready to be handled, update engine state
+      if(!c.fail && c.record !== null && c.record.ready) {
+        _update(c, c.record);
+      }
+    }
+
+    return rval;
+  };
+
+  /**
+   * Called when TLS protocol data has been received from somewhere and should
+   * be processed by the TLS engine.
+   *
+   * @param data the TLS protocol data, as a string, to process.
+   *
+   * @return 0 if the data could be processed, otherwise the number of bytes
+   *         required for data to be processed.
+   */
+  c.process = function(data) {
+    var rval = 0;
+
+    // buffer input data
+    if(data) {
+      c.input.putBytes(data);
+    }
+
+    // record handlers call c.process() without data to continue with the
+    // next record; while records are being processed, only flag that the
+    // loop below should continue instead of recursing, which could exhaust
+    // the call stack
+    if(_processing && typeof(data) === 'undefined') {
+      _processNext = true;
+      return rval;
+    }
+
+    // new data is processed right away, as before, even in a nested call
+    // (e.g., from a tlsDataReady handler that passes data synchronously
+    // between two connections)
+    var processing = _processing;
+    var processNext = _processNext;
+    _processing = true;
+    _processNext = false;
+    try {
+      // return value is based on the first record, as before
+      rval = _processRecord(c);
+      while(_processNext) {
+        _processNext = false;
+        _processRecord(c);
+      }
+    } finally {
+      _processing = processing;
+      _processNext = processNext;
+    }
+
+    return rval;
+  };
+
+  /**
+   * Requests that application data be packaged into a TLS record. The
+   * tlsDataReady handler will be called when the TLS record(s) have been
+   * prepared.
+   *
+   * @param data the application data, as a raw 'binary' encoded string, to
+   *          be sent; to send utf-16/utf-8 string data, use the return value
+   *          of util.encodeUtf8(str).
+   *
+   * @return true on success, false on failure.
+   */
+  c.prepare = function(data) {
+    tls.queue(c, tls.createRecord(c, {
+      type: tls.ContentType.application_data,
+      data: forge.util.createBuffer(data)
+    }));
+    return tls.flush(c);
+  };
+
+  /**
+   * Requests that a heartbeat request be packaged into a TLS record for
+   * transmission. The tlsDataReady handler will be called when TLS record(s)
+   * have been prepared.
+   *
+   * When a heartbeat response has been received, the heartbeatReceived
+   * handler will be called with the matching payload. This handler can
+   * be used to clear a retransmission timer, etc.
+   *
+   * @param payload the heartbeat data to send as the payload in the message.
+   * @param [payloadLength] the payload length to use, defaults to the
+   *          actual payload length.
+   *
+   * @return true on success, false on failure.
+   */
+  c.prepareHeartbeatRequest = function(payload, payloadLength) {
+    if(payload instanceof forge.util.ByteBuffer) {
+      payload = payload.bytes();
+    }
+    if(typeof payloadLength === 'undefined') {
+      payloadLength = payload.length;
+    }
+    c.expectedHeartbeatPayload = payload;
+    tls.queue(c, tls.createRecord(c, {
+      type: tls.ContentType.heartbeat,
+      data: tls.createHeartbeat(
+        tls.HeartbeatMessageType.heartbeat_request, payload, payloadLength)
+    }));
+    return tls.flush(c);
+  };
+
+  /**
+   * Closes the connection (sends a close_notify alert).
+   *
+   * @param clearFail true to clear the fail flag (default: true).
+   */
+  c.close = function(clearFail) {
+    // save session if connection didn't fail
+    if(!c.fail && c.sessionCache && c.session) {
+      // only need to preserve session ID, version, and security params
+      var session = {
+        id: c.session.id,
+        version: c.session.version,
+        sp: c.session.sp
+      };
+      session.sp.keys = null;
+      c.sessionCache.setSession(session.id, session);
+    }
+
+    if(c.open) {
+      // connection no longer open, clear input
+      c.open = false;
+      c.input.clear();
+
+      // if connected or handshaking, send an alert
+      if(c.isConnected || c.handshaking) {
+        c.isConnected = c.handshaking = false;
+
+        // send close_notify alert
+        tls.queue(c, tls.createAlert(c, {
+          level: tls.Alert.Level.warning,
+          description: tls.Alert.Description.close_notify
+        }));
+        tls.flush(c);
+      }
+
+      // call handler
+      c.closed(c);
+    }
+
+    // reset TLS connection, do not clear fail flag
+    c.reset(clearFail);
+  };
+
+  return c;
+};
+
+/* TLS API */
+module.exports = forge.tls = forge.tls || {};
+
+// expose non-functions
+for(var key in tls) {
+  if(typeof tls[key] !== 'function') {
+    forge.tls[key] = tls[key];
+  }
+}
+
+// expose prf_tls1 for testing
+forge.tls.prf_tls1 = prf_TLS1;
+
+// expose sha1 hmac method
+forge.tls.hmac_sha1 = hmac_sha1;
+
+// expose session cache creation
+forge.tls.createSessionCache = tls.createSessionCache;
+
+/**
+ * Creates a new TLS connection. This does not make any assumptions about the
+ * transport layer that TLS is working on top of, ie: it does not assume there
+ * is a TCP/IP connection or establish one. A TLS connection is totally
+ * abstracted away from the layer is runs on top of, it merely establishes a
+ * secure channel between a client" and a "server".
+ *
+ * A TLS connection contains 4 connection states: pending read and write, and
+ * current read and write.
+ *
+ * At initialization, the current read and write states will be null. Only once
+ * the security parameters have been set and the keys have been generated can
+ * the pending states be converted into current states. Current states will be
+ * updated for each record processed.
+ *
+ * A custom certificate verify callback may be provided to check information
+ * like the common name on the server's certificate. It will be called for
+ * every certificate in the chain. It has the following signature:
+ *
+ * variable func(c, certs, index, preVerify)
+ * Where:
+ * c         The TLS connection
+ * verified  Set to true if certificate was verified, otherwise the alert
+ *           tls.Alert.Description for why the certificate failed.
+ * depth     The current index in the chain, where 0 is the server's cert.
+ * certs     The certificate chain, *NOTE* if the server was anonymous then
+ *           the chain will be empty.
+ *
+ * The function returns true on success and on failure either the appropriate
+ * tls.Alert.Description or an object with 'alert' set to the appropriate
+ * tls.Alert.Description and 'message' set to a custom error message. If true
+ * is not returned then the connection will abort using, in order of
+ * availability, first the returned alert description, second the preVerify
+ * alert description, and lastly the default 'bad_certificate'.
+ *
+ * There are three callbacks that can be used to make use of client-side
+ * certificates where each takes the TLS connection as the first parameter:
+ *
+ * getCertificate(conn, hint)
+ *   The second parameter is a hint as to which certificate should be
+ *   returned. If the connection entity is a client, then the hint will be
+ *   the CertificateRequest message from the server that is part of the
+ *   TLS protocol. If the connection entity is a server, then it will be
+ *   the servername list provided via an SNI extension the ClientHello, if
+ *   one was provided (empty array if not). The hint can be examined to
+ *   determine which certificate to use (advanced). Most implementations
+ *   will just return a certificate. The return value must be a
+ *   PEM-formatted certificate or an array of PEM-formatted certificates
+ *   that constitute a certificate chain, with the first in the array/chain
+ *   being the client's certificate.
+ * getPrivateKey(conn, certificate)
+ *   The second parameter is an forge.pki X.509 certificate object that
+ *   is associated with the requested private key. The return value must
+ *   be a PEM-formatted private key.
+ * getSignature(conn, bytes, callback)
+ *   This callback can be used instead of getPrivateKey if the private key
+ *   is not directly accessible in javascript or should not be. For
+ *   instance, a secure external web service could provide the signature
+ *   in exchange for appropriate credentials. The second parameter is a
+ *   string of bytes to be signed that are part of the TLS protocol. These
+ *   bytes are used to verify that the private key for the previously
+ *   provided client-side certificate is accessible to the client. The
+ *   callback is a function that takes 2 parameters, the TLS connection
+ *   and the RSA encrypted (signed) bytes as a string. This callback must
+ *   be called once the signature is ready.
+ *
+ * @param options the options for this connection:
+ *   server: true if the connection is server-side, false for client.
+ *   sessionId: a session ID to reuse, null for a new connection.
+ *   caStore: an array of certificates to trust.
+ *   sessionCache: a session cache to use.
+ *   cipherSuites: an optional array of cipher suites to use,
+ *     see tls.CipherSuites.
+ *   connected: function(conn) called when the first handshake completes.
+ *   virtualHost: the virtual server name to use in a TLS SNI extension.
+ *   verifyClient: true to require a client certificate in server mode,
+ *     'optional' to request one, false not to (default: false).
+ *   verify: a handler used to custom verify certificates in the chain.
+ *   verifyOptions: an object with options for the certificate chain validation.
+ *     See documentation of pki.verifyCertificateChain for possible options.
+ *     verifyOptions.verify is ignored. If you wish to specify a verify handler
+ *     use the verify key.
+ *   getCertificate: an optional callback used to get a certificate or
+ *     a chain of certificates (as an array).
+ *   getPrivateKey: an optional callback used to get a private key.
+ *   getSignature: an optional callback used to get a signature.
+ *   tlsDataReady: function(conn) called when TLS protocol data has been
+ *     prepared and is ready to be used (typically sent over a socket
+ *     connection to its destination), read from conn.tlsData buffer.
+ *   dataReady: function(conn) called when application data has
+ *     been parsed from a TLS record and should be consumed by the
+ *     application, read from conn.data buffer.
+ *   closed: function(conn) called when the connection has been closed.
+ *   error: function(conn, error) called when there was an error.
+ *   deflate: function(inBytes) if provided, will deflate TLS records using
+ *     the deflate algorithm if the server supports it.
+ *   inflate: function(inBytes) if provided, will inflate TLS records using
+ *     the deflate algorithm if the server supports it.
+ *
+ * @return the new TLS connection.
+ */
+forge.tls.createConnection = tls.createConnection;