source: trip-planner-front/node_modules/node-forge/lib/tls.js@ 6fe77af

Last change on this file since 6fe77af was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 129.9 KB
Line 
1/**
2 * A Javascript implementation of Transport Layer Security (TLS).
3 *
4 * @author Dave Longley
5 *
6 * Copyright (c) 2009-2014 Digital Bazaar, Inc.
7 *
8 * The TLS Handshake Protocol involves the following steps:
9 *
10 * - Exchange hello messages to agree on algorithms, exchange random values,
11 * and check for session resumption.
12 *
13 * - Exchange the necessary cryptographic parameters to allow the client and
14 * server to agree on a premaster secret.
15 *
16 * - Exchange certificates and cryptographic information to allow the client
17 * and server to authenticate themselves.
18 *
19 * - Generate a master secret from the premaster secret and exchanged random
20 * values.
21 *
22 * - Provide security parameters to the record layer.
23 *
24 * - Allow the client and server to verify that their peer has calculated the
25 * same security parameters and that the handshake occurred without tampering
26 * by an attacker.
27 *
28 * Up to 4 different messages may be sent during a key exchange. The server
29 * certificate, the server key exchange, the client certificate, and the
30 * client key exchange.
31 *
32 * A typical handshake (from the client's perspective).
33 *
34 * 1. Client sends ClientHello.
35 * 2. Client receives ServerHello.
36 * 3. Client receives optional Certificate.
37 * 4. Client receives optional ServerKeyExchange.
38 * 5. Client receives ServerHelloDone.
39 * 6. Client sends optional Certificate.
40 * 7. Client sends ClientKeyExchange.
41 * 8. Client sends optional CertificateVerify.
42 * 9. Client sends ChangeCipherSpec.
43 * 10. Client sends Finished.
44 * 11. Client receives ChangeCipherSpec.
45 * 12. Client receives Finished.
46 * 13. Client sends/receives application data.
47 *
48 * To reuse an existing session:
49 *
50 * 1. Client sends ClientHello with session ID for reuse.
51 * 2. Client receives ServerHello with same session ID if reusing.
52 * 3. Client receives ChangeCipherSpec message if reusing.
53 * 4. Client receives Finished.
54 * 5. Client sends ChangeCipherSpec.
55 * 6. Client sends Finished.
56 *
57 * Note: Client ignores HelloRequest if in the middle of a handshake.
58 *
59 * Record Layer:
60 *
61 * The record layer fragments information blocks into TLSPlaintext records
62 * carrying data in chunks of 2^14 bytes or less. Client message boundaries are
63 * not preserved in the record layer (i.e., multiple client messages of the
64 * same ContentType MAY be coalesced into a single TLSPlaintext record, or a
65 * single message MAY be fragmented across several records).
66 *
67 * struct {
68 * uint8 major;
69 * uint8 minor;
70 * } ProtocolVersion;
71 *
72 * struct {
73 * ContentType type;
74 * ProtocolVersion version;
75 * uint16 length;
76 * opaque fragment[TLSPlaintext.length];
77 * } TLSPlaintext;
78 *
79 * type:
80 * The higher-level protocol used to process the enclosed fragment.
81 *
82 * version:
83 * The version of the protocol being employed. TLS Version 1.2 uses version
84 * {3, 3}. TLS Version 1.0 uses version {3, 1}. Note that a client that
85 * supports multiple versions of TLS may not know what version will be
86 * employed before it receives the ServerHello.
87 *
88 * length:
89 * The length (in bytes) of the following TLSPlaintext.fragment. The length
90 * MUST NOT exceed 2^14 = 16384 bytes.
91 *
92 * fragment:
93 * The application data. This data is transparent and treated as an
94 * independent block to be dealt with by the higher-level protocol specified
95 * by the type field.
96 *
97 * Implementations MUST NOT send zero-length fragments of Handshake, Alert, or
98 * ChangeCipherSpec content types. Zero-length fragments of Application data
99 * MAY be sent as they are potentially useful as a traffic analysis
100 * countermeasure.
101 *
102 * Note: Data of different TLS record layer content types MAY be interleaved.
103 * Application data is generally of lower precedence for transmission than
104 * other content types. However, records MUST be delivered to the network in
105 * the same order as they are protected by the record layer. Recipients MUST
106 * receive and process interleaved application layer traffic during handshakes
107 * subsequent to the first one on a connection.
108 *
109 * struct {
110 * ContentType type; // same as TLSPlaintext.type
111 * ProtocolVersion version;// same as TLSPlaintext.version
112 * uint16 length;
113 * opaque fragment[TLSCompressed.length];
114 * } TLSCompressed;
115 *
116 * length:
117 * The length (in bytes) of the following TLSCompressed.fragment.
118 * The length MUST NOT exceed 2^14 + 1024.
119 *
120 * fragment:
121 * The compressed form of TLSPlaintext.fragment.
122 *
123 * Note: A CompressionMethod.null operation is an identity operation; no fields
124 * are altered. In this implementation, since no compression is supported,
125 * uncompressed records are always the same as compressed records.
126 *
127 * Encryption Information:
128 *
129 * The encryption and MAC functions translate a TLSCompressed structure into a
130 * TLSCiphertext. The decryption functions reverse the process. The MAC of the
131 * record also includes a sequence number so that missing, extra, or repeated
132 * messages are detectable.
133 *
134 * struct {
135 * ContentType type;
136 * ProtocolVersion version;
137 * uint16 length;
138 * select (SecurityParameters.cipher_type) {
139 * case stream: GenericStreamCipher;
140 * case block: GenericBlockCipher;
141 * case aead: GenericAEADCipher;
142 * } fragment;
143 * } TLSCiphertext;
144 *
145 * type:
146 * The type field is identical to TLSCompressed.type.
147 *
148 * version:
149 * The version field is identical to TLSCompressed.version.
150 *
151 * length:
152 * The length (in bytes) of the following TLSCiphertext.fragment.
153 * The length MUST NOT exceed 2^14 + 2048.
154 *
155 * fragment:
156 * The encrypted form of TLSCompressed.fragment, with the MAC.
157 *
158 * Note: Only CBC Block Ciphers are supported by this implementation.
159 *
160 * The TLSCompressed.fragment structures are converted to/from block
161 * TLSCiphertext.fragment structures.
162 *
163 * struct {
164 * opaque IV[SecurityParameters.record_iv_length];
165 * block-ciphered struct {
166 * opaque content[TLSCompressed.length];
167 * opaque MAC[SecurityParameters.mac_length];
168 * uint8 padding[GenericBlockCipher.padding_length];
169 * uint8 padding_length;
170 * };
171 * } GenericBlockCipher;
172 *
173 * The MAC is generated as described in Section 6.2.3.1.
174 *
175 * IV:
176 * The Initialization Vector (IV) SHOULD be chosen at random, and MUST be
177 * unpredictable. Note that in versions of TLS prior to 1.1, there was no
178 * IV field, and the last ciphertext block of the previous record (the "CBC
179 * residue") was used as the IV. This was changed to prevent the attacks
180 * described in [CBCATT]. For block ciphers, the IV length is of length
181 * SecurityParameters.record_iv_length, which is equal to the
182 * SecurityParameters.block_size.
183 *
184 * padding:
185 * Padding that is added to force the length of the plaintext to be an
186 * integral multiple of the block cipher's block length. The padding MAY be
187 * any length up to 255 bytes, as long as it results in the
188 * TLSCiphertext.length being an integral multiple of the block length.
189 * Lengths longer than necessary might be desirable to frustrate attacks on
190 * a protocol that are based on analysis of the lengths of exchanged
191 * messages. Each uint8 in the padding data vector MUST be filled with the
192 * padding length value. The receiver MUST check this padding and MUST use
193 * the bad_record_mac alert to indicate padding errors.
194 *
195 * padding_length:
196 * The padding length MUST be such that the total size of the
197 * GenericBlockCipher structure is a multiple of the cipher's block length.
198 * Legal values range from zero to 255, inclusive. This length specifies the
199 * length of the padding field exclusive of the padding_length field itself.
200 *
201 * The encrypted data length (TLSCiphertext.length) is one more than the sum of
202 * SecurityParameters.block_length, TLSCompressed.length,
203 * SecurityParameters.mac_length, and padding_length.
204 *
205 * Example: If the block length is 8 bytes, the content length
206 * (TLSCompressed.length) is 61 bytes, and the MAC length is 20 bytes, then the
207 * length before padding is 82 bytes (this does not include the IV. Thus, the
208 * padding length modulo 8 must be equal to 6 in order to make the total length
209 * an even multiple of 8 bytes (the block length). The padding length can be
210 * 6, 14, 22, and so on, through 254. If the padding length were the minimum
211 * necessary, 6, the padding would be 6 bytes, each containing the value 6.
212 * Thus, the last 8 octets of the GenericBlockCipher before block encryption
213 * would be xx 06 06 06 06 06 06 06, where xx is the last octet of the MAC.
214 *
215 * Note: With block ciphers in CBC mode (Cipher Block Chaining), it is critical
216 * that the entire plaintext of the record be known before any ciphertext is
217 * transmitted. Otherwise, it is possible for the attacker to mount the attack
218 * described in [CBCATT].
219 *
220 * Implementation note: Canvel et al. [CBCTIME] have demonstrated a timing
221 * attack on CBC padding based on the time required to compute the MAC. In
222 * order to defend against this attack, implementations MUST ensure that
223 * record processing time is essentially the same whether or not the padding
224 * is correct. In general, the best way to do this is to compute the MAC even
225 * if the padding is incorrect, and only then reject the packet. For instance,
226 * if the pad appears to be incorrect, the implementation might assume a
227 * zero-length pad and then compute the MAC. This leaves a small timing
228 * channel, since MAC performance depends, to some extent, on the size of the
229 * data fragment, but it is not believed to be large enough to be exploitable,
230 * due to the large block size of existing MACs and the small size of the
231 * timing signal.
232 */
233var forge = require('./forge');
234require('./asn1');
235require('./hmac');
236require('./md5');
237require('./pem');
238require('./pki');
239require('./random');
240require('./sha1');
241require('./util');
242
243/**
244 * Generates pseudo random bytes by mixing the result of two hash functions,
245 * MD5 and SHA-1.
246 *
247 * prf_TLS1(secret, label, seed) =
248 * P_MD5(S1, label + seed) XOR P_SHA-1(S2, label + seed);
249 *
250 * Each P_hash function functions as follows:
251 *
252 * P_hash(secret, seed) = HMAC_hash(secret, A(1) + seed) +
253 * HMAC_hash(secret, A(2) + seed) +
254 * HMAC_hash(secret, A(3) + seed) + ...
255 * A() is defined as:
256 * A(0) = seed
257 * A(i) = HMAC_hash(secret, A(i-1))
258 *
259 * The '+' operator denotes concatenation.
260 *
261 * As many iterations A(N) as are needed are performed to generate enough
262 * pseudo random byte output. If an iteration creates more data than is
263 * necessary, then it is truncated.
264 *
265 * Therefore:
266 * A(1) = HMAC_hash(secret, A(0))
267 * = HMAC_hash(secret, seed)
268 * A(2) = HMAC_hash(secret, A(1))
269 * = HMAC_hash(secret, HMAC_hash(secret, seed))
270 *
271 * Therefore:
272 * P_hash(secret, seed) =
273 * HMAC_hash(secret, HMAC_hash(secret, A(0)) + seed) +
274 * HMAC_hash(secret, HMAC_hash(secret, A(1)) + seed) +
275 * ...
276 *
277 * Therefore:
278 * P_hash(secret, seed) =
279 * HMAC_hash(secret, HMAC_hash(secret, seed) + seed) +
280 * HMAC_hash(secret, HMAC_hash(secret, HMAC_hash(secret, seed)) + seed) +
281 * ...
282 *
283 * @param secret the secret to use.
284 * @param label the label to use.
285 * @param seed the seed value to use.
286 * @param length the number of bytes to generate.
287 *
288 * @return the pseudo random bytes in a byte buffer.
289 */
290var prf_TLS1 = function(secret, label, seed, length) {
291 var rval = forge.util.createBuffer();
292
293 /* For TLS 1.0, the secret is split in half, into two secrets of equal
294 length. If the secret has an odd length then the last byte of the first
295 half will be the same as the first byte of the second. The length of the
296 two secrets is half of the secret rounded up. */
297 var idx = (secret.length >> 1);
298 var slen = idx + (secret.length & 1);
299 var s1 = secret.substr(0, slen);
300 var s2 = secret.substr(idx, slen);
301 var ai = forge.util.createBuffer();
302 var hmac = forge.hmac.create();
303 seed = label + seed;
304
305 // determine the number of iterations that must be performed to generate
306 // enough output bytes, md5 creates 16 byte hashes, sha1 creates 20
307 var md5itr = Math.ceil(length / 16);
308 var sha1itr = Math.ceil(length / 20);
309
310 // do md5 iterations
311 hmac.start('MD5', s1);
312 var md5bytes = forge.util.createBuffer();
313 ai.putBytes(seed);
314 for(var i = 0; i < md5itr; ++i) {
315 // HMAC_hash(secret, A(i-1))
316 hmac.start(null, null);
317 hmac.update(ai.getBytes());
318 ai.putBuffer(hmac.digest());
319
320 // HMAC_hash(secret, A(i) + seed)
321 hmac.start(null, null);
322 hmac.update(ai.bytes() + seed);
323 md5bytes.putBuffer(hmac.digest());
324 }
325
326 // do sha1 iterations
327 hmac.start('SHA1', s2);
328 var sha1bytes = forge.util.createBuffer();
329 ai.clear();
330 ai.putBytes(seed);
331 for(var i = 0; i < sha1itr; ++i) {
332 // HMAC_hash(secret, A(i-1))
333 hmac.start(null, null);
334 hmac.update(ai.getBytes());
335 ai.putBuffer(hmac.digest());
336
337 // HMAC_hash(secret, A(i) + seed)
338 hmac.start(null, null);
339 hmac.update(ai.bytes() + seed);
340 sha1bytes.putBuffer(hmac.digest());
341 }
342
343 // XOR the md5 bytes with the sha1 bytes
344 rval.putBytes(forge.util.xorBytes(
345 md5bytes.getBytes(), sha1bytes.getBytes(), length));
346
347 return rval;
348};
349
350/**
351 * Generates pseudo random bytes using a SHA256 algorithm. For TLS 1.2.
352 *
353 * @param secret the secret to use.
354 * @param label the label to use.
355 * @param seed the seed value to use.
356 * @param length the number of bytes to generate.
357 *
358 * @return the pseudo random bytes in a byte buffer.
359 */
360var prf_sha256 = function(secret, label, seed, length) {
361 // FIXME: implement me for TLS 1.2
362};
363
364/**
365 * Gets a MAC for a record using the SHA-1 hash algorithm.
366 *
367 * @param key the mac key.
368 * @param state the sequence number (array of two 32-bit integers).
369 * @param record the record.
370 *
371 * @return the sha-1 hash (20 bytes) for the given record.
372 */
373var hmac_sha1 = function(key, seqNum, record) {
374 /* MAC is computed like so:
375 HMAC_hash(
376 key, seqNum +
377 TLSCompressed.type +
378 TLSCompressed.version +
379 TLSCompressed.length +
380 TLSCompressed.fragment)
381 */
382 var hmac = forge.hmac.create();
383 hmac.start('SHA1', key);
384 var b = forge.util.createBuffer();
385 b.putInt32(seqNum[0]);
386 b.putInt32(seqNum[1]);
387 b.putByte(record.type);
388 b.putByte(record.version.major);
389 b.putByte(record.version.minor);
390 b.putInt16(record.length);
391 b.putBytes(record.fragment.bytes());
392 hmac.update(b.getBytes());
393 return hmac.digest().getBytes();
394};
395
396/**
397 * Compresses the TLSPlaintext record into a TLSCompressed record using the
398 * deflate algorithm.
399 *
400 * @param c the TLS connection.
401 * @param record the TLSPlaintext record to compress.
402 * @param s the ConnectionState to use.
403 *
404 * @return true on success, false on failure.
405 */
406var deflate = function(c, record, s) {
407 var rval = false;
408
409 try {
410 var bytes = c.deflate(record.fragment.getBytes());
411 record.fragment = forge.util.createBuffer(bytes);
412 record.length = bytes.length;
413 rval = true;
414 } catch(ex) {
415 // deflate error, fail out
416 }
417
418 return rval;
419};
420
421/**
422 * Decompresses the TLSCompressed record into a TLSPlaintext record using the
423 * deflate algorithm.
424 *
425 * @param c the TLS connection.
426 * @param record the TLSCompressed record to decompress.
427 * @param s the ConnectionState to use.
428 *
429 * @return true on success, false on failure.
430 */
431var inflate = function(c, record, s) {
432 var rval = false;
433
434 try {
435 var bytes = c.inflate(record.fragment.getBytes());
436 record.fragment = forge.util.createBuffer(bytes);
437 record.length = bytes.length;
438 rval = true;
439 } catch(ex) {
440 // inflate error, fail out
441 }
442
443 return rval;
444};
445
446/**
447 * Reads a TLS variable-length vector from a byte buffer.
448 *
449 * Variable-length vectors are defined by specifying a subrange of legal
450 * lengths, inclusively, using the notation <floor..ceiling>. When these are
451 * encoded, the actual length precedes the vector's contents in the byte
452 * stream. The length will be in the form of a number consuming as many bytes
453 * as required to hold the vector's specified maximum (ceiling) length. A
454 * variable-length vector with an actual length field of zero is referred to
455 * as an empty vector.
456 *
457 * @param b the byte buffer.
458 * @param lenBytes the number of bytes required to store the length.
459 *
460 * @return the resulting byte buffer.
461 */
462var readVector = function(b, lenBytes) {
463 var len = 0;
464 switch(lenBytes) {
465 case 1:
466 len = b.getByte();
467 break;
468 case 2:
469 len = b.getInt16();
470 break;
471 case 3:
472 len = b.getInt24();
473 break;
474 case 4:
475 len = b.getInt32();
476 break;
477 }
478
479 // read vector bytes into a new buffer
480 return forge.util.createBuffer(b.getBytes(len));
481};
482
483/**
484 * Writes a TLS variable-length vector to a byte buffer.
485 *
486 * @param b the byte buffer.
487 * @param lenBytes the number of bytes required to store the length.
488 * @param v the byte buffer vector.
489 */
490var writeVector = function(b, lenBytes, v) {
491 // encode length at the start of the vector, where the number of bytes for
492 // the length is the maximum number of bytes it would take to encode the
493 // vector's ceiling
494 b.putInt(v.length(), lenBytes << 3);
495 b.putBuffer(v);
496};
497
498/**
499 * The tls implementation.
500 */
501var tls = {};
502
503/**
504 * Version: TLS 1.2 = 3.3, TLS 1.1 = 3.2, TLS 1.0 = 3.1. Both TLS 1.1 and
505 * TLS 1.2 were still too new (ie: openSSL didn't implement them) at the time
506 * of this implementation so TLS 1.0 was implemented instead.
507 */
508tls.Versions = {
509 TLS_1_0: {major: 3, minor: 1},
510 TLS_1_1: {major: 3, minor: 2},
511 TLS_1_2: {major: 3, minor: 3}
512};
513tls.SupportedVersions = [
514 tls.Versions.TLS_1_1,
515 tls.Versions.TLS_1_0
516];
517tls.Version = tls.SupportedVersions[0];
518
519/**
520 * Maximum fragment size. True maximum is 16384, but we fragment before that
521 * to allow for unusual small increases during compression.
522 */
523tls.MaxFragment = 16384 - 1024;
524
525/**
526 * Whether this entity is considered the "client" or "server".
527 * enum { server, client } ConnectionEnd;
528 */
529tls.ConnectionEnd = {
530 server: 0,
531 client: 1
532};
533
534/**
535 * Pseudo-random function algorithm used to generate keys from the master
536 * secret.
537 * enum { tls_prf_sha256 } PRFAlgorithm;
538 */
539tls.PRFAlgorithm = {
540 tls_prf_sha256: 0
541};
542
543/**
544 * Bulk encryption algorithms.
545 * enum { null, rc4, des3, aes } BulkCipherAlgorithm;
546 */
547tls.BulkCipherAlgorithm = {
548 none: null,
549 rc4: 0,
550 des3: 1,
551 aes: 2
552};
553
554/**
555 * Cipher types.
556 * enum { stream, block, aead } CipherType;
557 */
558tls.CipherType = {
559 stream: 0,
560 block: 1,
561 aead: 2
562};
563
564/**
565 * MAC (Message Authentication Code) algorithms.
566 * enum { null, hmac_md5, hmac_sha1, hmac_sha256,
567 * hmac_sha384, hmac_sha512} MACAlgorithm;
568 */
569tls.MACAlgorithm = {
570 none: null,
571 hmac_md5: 0,
572 hmac_sha1: 1,
573 hmac_sha256: 2,
574 hmac_sha384: 3,
575 hmac_sha512: 4
576};
577
578/**
579 * Compression algorithms.
580 * enum { null(0), deflate(1), (255) } CompressionMethod;
581 */
582tls.CompressionMethod = {
583 none: 0,
584 deflate: 1
585};
586
587/**
588 * TLS record content types.
589 * enum {
590 * change_cipher_spec(20), alert(21), handshake(22),
591 * application_data(23), (255)
592 * } ContentType;
593 */
594tls.ContentType = {
595 change_cipher_spec: 20,
596 alert: 21,
597 handshake: 22,
598 application_data: 23,
599 heartbeat: 24
600};
601
602/**
603 * TLS handshake types.
604 * enum {
605 * hello_request(0), client_hello(1), server_hello(2),
606 * certificate(11), server_key_exchange (12),
607 * certificate_request(13), server_hello_done(14),
608 * certificate_verify(15), client_key_exchange(16),
609 * finished(20), (255)
610 * } HandshakeType;
611 */
612tls.HandshakeType = {
613 hello_request: 0,
614 client_hello: 1,
615 server_hello: 2,
616 certificate: 11,
617 server_key_exchange: 12,
618 certificate_request: 13,
619 server_hello_done: 14,
620 certificate_verify: 15,
621 client_key_exchange: 16,
622 finished: 20
623};
624
625/**
626 * TLS Alert Protocol.
627 *
628 * enum { warning(1), fatal(2), (255) } AlertLevel;
629 *
630 * enum {
631 * close_notify(0),
632 * unexpected_message(10),
633 * bad_record_mac(20),
634 * decryption_failed(21),
635 * record_overflow(22),
636 * decompression_failure(30),
637 * handshake_failure(40),
638 * bad_certificate(42),
639 * unsupported_certificate(43),
640 * certificate_revoked(44),
641 * certificate_expired(45),
642 * certificate_unknown(46),
643 * illegal_parameter(47),
644 * unknown_ca(48),
645 * access_denied(49),
646 * decode_error(50),
647 * decrypt_error(51),
648 * export_restriction(60),
649 * protocol_version(70),
650 * insufficient_security(71),
651 * internal_error(80),
652 * user_canceled(90),
653 * no_renegotiation(100),
654 * (255)
655 * } AlertDescription;
656 *
657 * struct {
658 * AlertLevel level;
659 * AlertDescription description;
660 * } Alert;
661 */
662tls.Alert = {};
663tls.Alert.Level = {
664 warning: 1,
665 fatal: 2
666};
667tls.Alert.Description = {
668 close_notify: 0,
669 unexpected_message: 10,
670 bad_record_mac: 20,
671 decryption_failed: 21,
672 record_overflow: 22,
673 decompression_failure: 30,
674 handshake_failure: 40,
675 bad_certificate: 42,
676 unsupported_certificate: 43,
677 certificate_revoked: 44,
678 certificate_expired: 45,
679 certificate_unknown: 46,
680 illegal_parameter: 47,
681 unknown_ca: 48,
682 access_denied: 49,
683 decode_error: 50,
684 decrypt_error: 51,
685 export_restriction: 60,
686 protocol_version: 70,
687 insufficient_security: 71,
688 internal_error: 80,
689 user_canceled: 90,
690 no_renegotiation: 100
691};
692
693/**
694 * TLS Heartbeat Message types.
695 * enum {
696 * heartbeat_request(1),
697 * heartbeat_response(2),
698 * (255)
699 * } HeartbeatMessageType;
700 */
701tls.HeartbeatMessageType = {
702 heartbeat_request: 1,
703 heartbeat_response: 2
704};
705
706/**
707 * Supported cipher suites.
708 */
709tls.CipherSuites = {};
710
711/**
712 * Gets a supported cipher suite from its 2 byte ID.
713 *
714 * @param twoBytes two bytes in a string.
715 *
716 * @return the matching supported cipher suite or null.
717 */
718tls.getCipherSuite = function(twoBytes) {
719 var rval = null;
720 for(var key in tls.CipherSuites) {
721 var cs = tls.CipherSuites[key];
722 if(cs.id[0] === twoBytes.charCodeAt(0) &&
723 cs.id[1] === twoBytes.charCodeAt(1)) {
724 rval = cs;
725 break;
726 }
727 }
728 return rval;
729};
730
731/**
732 * Called when an unexpected record is encountered.
733 *
734 * @param c the connection.
735 * @param record the record.
736 */
737tls.handleUnexpected = function(c, record) {
738 // if connection is client and closed, ignore unexpected messages
739 var ignore = (!c.open && c.entity === tls.ConnectionEnd.client);
740 if(!ignore) {
741 c.error(c, {
742 message: 'Unexpected message. Received TLS record out of order.',
743 send: true,
744 alert: {
745 level: tls.Alert.Level.fatal,
746 description: tls.Alert.Description.unexpected_message
747 }
748 });
749 }
750};
751
752/**
753 * Called when a client receives a HelloRequest record.
754 *
755 * @param c the connection.
756 * @param record the record.
757 * @param length the length of the handshake message.
758 */
759tls.handleHelloRequest = function(c, record, length) {
760 // ignore renegotiation requests from the server during a handshake, but
761 // if handshaking, send a warning alert that renegotation is denied
762 if(!c.handshaking && c.handshakes > 0) {
763 // send alert warning
764 tls.queue(c, tls.createAlert(c, {
765 level: tls.Alert.Level.warning,
766 description: tls.Alert.Description.no_renegotiation
767 }));
768 tls.flush(c);
769 }
770
771 // continue
772 c.process();
773};
774
775/**
776 * Parses a hello message from a ClientHello or ServerHello record.
777 *
778 * @param record the record to parse.
779 *
780 * @return the parsed message.
781 */
782tls.parseHelloMessage = function(c, record, length) {
783 var msg = null;
784
785 var client = (c.entity === tls.ConnectionEnd.client);
786
787 // minimum of 38 bytes in message
788 if(length < 38) {
789 c.error(c, {
790 message: client ?
791 'Invalid ServerHello message. Message too short.' :
792 'Invalid ClientHello message. Message too short.',
793 send: true,
794 alert: {
795 level: tls.Alert.Level.fatal,
796 description: tls.Alert.Description.illegal_parameter
797 }
798 });
799 } else {
800 // use 'remaining' to calculate # of remaining bytes in the message
801 var b = record.fragment;
802 var remaining = b.length();
803 msg = {
804 version: {
805 major: b.getByte(),
806 minor: b.getByte()
807 },
808 random: forge.util.createBuffer(b.getBytes(32)),
809 session_id: readVector(b, 1),
810 extensions: []
811 };
812 if(client) {
813 msg.cipher_suite = b.getBytes(2);
814 msg.compression_method = b.getByte();
815 } else {
816 msg.cipher_suites = readVector(b, 2);
817 msg.compression_methods = readVector(b, 1);
818 }
819
820 // read extensions if there are any bytes left in the message
821 remaining = length - (remaining - b.length());
822 if(remaining > 0) {
823 // parse extensions
824 var exts = readVector(b, 2);
825 while(exts.length() > 0) {
826 msg.extensions.push({
827 type: [exts.getByte(), exts.getByte()],
828 data: readVector(exts, 2)
829 });
830 }
831
832 // TODO: make extension support modular
833 if(!client) {
834 for(var i = 0; i < msg.extensions.length; ++i) {
835 var ext = msg.extensions[i];
836
837 // support SNI extension
838 if(ext.type[0] === 0x00 && ext.type[1] === 0x00) {
839 // get server name list
840 var snl = readVector(ext.data, 2);
841 while(snl.length() > 0) {
842 // read server name type
843 var snType = snl.getByte();
844
845 // only HostName type (0x00) is known, break out if
846 // another type is detected
847 if(snType !== 0x00) {
848 break;
849 }
850
851 // add host name to server name list
852 c.session.extensions.server_name.serverNameList.push(
853 readVector(snl, 2).getBytes());
854 }
855 }
856 }
857 }
858 }
859
860 // version already set, do not allow version change
861 if(c.session.version) {
862 if(msg.version.major !== c.session.version.major ||
863 msg.version.minor !== c.session.version.minor) {
864 return c.error(c, {
865 message: 'TLS version change is disallowed during renegotiation.',
866 send: true,
867 alert: {
868 level: tls.Alert.Level.fatal,
869 description: tls.Alert.Description.protocol_version
870 }
871 });
872 }
873 }
874
875 // get the chosen (ServerHello) cipher suite
876 if(client) {
877 // FIXME: should be checking configured acceptable cipher suites
878 c.session.cipherSuite = tls.getCipherSuite(msg.cipher_suite);
879 } else {
880 // get a supported preferred (ClientHello) cipher suite
881 // choose the first supported cipher suite
882 var tmp = forge.util.createBuffer(msg.cipher_suites.bytes());
883 while(tmp.length() > 0) {
884 // FIXME: should be checking configured acceptable suites
885 // cipher suites take up 2 bytes
886 c.session.cipherSuite = tls.getCipherSuite(tmp.getBytes(2));
887 if(c.session.cipherSuite !== null) {
888 break;
889 }
890 }
891 }
892
893 // cipher suite not supported
894 if(c.session.cipherSuite === null) {
895 return c.error(c, {
896 message: 'No cipher suites in common.',
897 send: true,
898 alert: {
899 level: tls.Alert.Level.fatal,
900 description: tls.Alert.Description.handshake_failure
901 },
902 cipherSuite: forge.util.bytesToHex(msg.cipher_suite)
903 });
904 }
905
906 // TODO: handle compression methods
907 if(client) {
908 c.session.compressionMethod = msg.compression_method;
909 } else {
910 // no compression
911 c.session.compressionMethod = tls.CompressionMethod.none;
912 }
913 }
914
915 return msg;
916};
917
918/**
919 * Creates security parameters for the given connection based on the given
920 * hello message.
921 *
922 * @param c the TLS connection.
923 * @param msg the hello message.
924 */
925tls.createSecurityParameters = function(c, msg) {
926 /* Note: security params are from TLS 1.2, some values like prf_algorithm
927 are ignored for TLS 1.0/1.1 and the builtin as specified in the spec is
928 used. */
929
930 // TODO: handle other options from server when more supported
931
932 // get client and server randoms
933 var client = (c.entity === tls.ConnectionEnd.client);
934 var msgRandom = msg.random.bytes();
935 var cRandom = client ? c.session.sp.client_random : msgRandom;
936 var sRandom = client ? msgRandom : tls.createRandom().getBytes();
937
938 // create new security parameters
939 c.session.sp = {
940 entity: c.entity,
941 prf_algorithm: tls.PRFAlgorithm.tls_prf_sha256,
942 bulk_cipher_algorithm: null,
943 cipher_type: null,
944 enc_key_length: null,
945 block_length: null,
946 fixed_iv_length: null,
947 record_iv_length: null,
948 mac_algorithm: null,
949 mac_length: null,
950 mac_key_length: null,
951 compression_algorithm: c.session.compressionMethod,
952 pre_master_secret: null,
953 master_secret: null,
954 client_random: cRandom,
955 server_random: sRandom
956 };
957};
958
959/**
960 * Called when a client receives a ServerHello record.
961 *
962 * When a ServerHello message will be sent:
963 * The server will send this message in response to a client hello message
964 * when it was able to find an acceptable set of algorithms. If it cannot
965 * find such a match, it will respond with a handshake failure alert.
966 *
967 * uint24 length;
968 * struct {
969 * ProtocolVersion server_version;
970 * Random random;
971 * SessionID session_id;
972 * CipherSuite cipher_suite;
973 * CompressionMethod compression_method;
974 * select(extensions_present) {
975 * case false:
976 * struct {};
977 * case true:
978 * Extension extensions<0..2^16-1>;
979 * };
980 * } ServerHello;
981 *
982 * @param c the connection.
983 * @param record the record.
984 * @param length the length of the handshake message.
985 */
986tls.handleServerHello = function(c, record, length) {
987 var msg = tls.parseHelloMessage(c, record, length);
988 if(c.fail) {
989 return;
990 }
991
992 // ensure server version is compatible
993 if(msg.version.minor <= c.version.minor) {
994 c.version.minor = msg.version.minor;
995 } else {
996 return c.error(c, {
997 message: 'Incompatible TLS version.',
998 send: true,
999 alert: {
1000 level: tls.Alert.Level.fatal,
1001 description: tls.Alert.Description.protocol_version
1002 }
1003 });
1004 }
1005
1006 // indicate session version has been set
1007 c.session.version = c.version;
1008
1009 // get the session ID from the message
1010 var sessionId = msg.session_id.bytes();
1011
1012 // if the session ID is not blank and matches the cached one, resume
1013 // the session
1014 if(sessionId.length > 0 && sessionId === c.session.id) {
1015 // resuming session, expect a ChangeCipherSpec next
1016 c.expect = SCC;
1017 c.session.resuming = true;
1018
1019 // get new server random
1020 c.session.sp.server_random = msg.random.bytes();
1021 } else {
1022 // not resuming, expect a server Certificate message next
1023 c.expect = SCE;
1024 c.session.resuming = false;
1025
1026 // create new security parameters
1027 tls.createSecurityParameters(c, msg);
1028 }
1029
1030 // set new session ID
1031 c.session.id = sessionId;
1032
1033 // continue
1034 c.process();
1035};
1036
1037/**
1038 * Called when a server receives a ClientHello record.
1039 *
1040 * When a ClientHello message will be sent:
1041 * When a client first connects to a server it is required to send the
1042 * client hello as its first message. The client can also send a client
1043 * hello in response to a hello request or on its own initiative in order
1044 * to renegotiate the security parameters in an existing connection.
1045 *
1046 * @param c the connection.
1047 * @param record the record.
1048 * @param length the length of the handshake message.
1049 */
1050tls.handleClientHello = function(c, record, length) {
1051 var msg = tls.parseHelloMessage(c, record, length);
1052 if(c.fail) {
1053 return;
1054 }
1055
1056 // get the session ID from the message
1057 var sessionId = msg.session_id.bytes();
1058
1059 // see if the given session ID is in the cache
1060 var session = null;
1061 if(c.sessionCache) {
1062 session = c.sessionCache.getSession(sessionId);
1063 if(session === null) {
1064 // session ID not found
1065 sessionId = '';
1066 } else if(session.version.major !== msg.version.major ||
1067 session.version.minor > msg.version.minor) {
1068 // if session version is incompatible with client version, do not resume
1069 session = null;
1070 sessionId = '';
1071 }
1072 }
1073
1074 // no session found to resume, generate a new session ID
1075 if(sessionId.length === 0) {
1076 sessionId = forge.random.getBytes(32);
1077 }
1078
1079 // update session
1080 c.session.id = sessionId;
1081 c.session.clientHelloVersion = msg.version;
1082 c.session.sp = {};
1083 if(session) {
1084 // use version and security parameters from resumed session
1085 c.version = c.session.version = session.version;
1086 c.session.sp = session.sp;
1087 } else {
1088 // use highest compatible minor version
1089 var version;
1090 for(var i = 1; i < tls.SupportedVersions.length; ++i) {
1091 version = tls.SupportedVersions[i];
1092 if(version.minor <= msg.version.minor) {
1093 break;
1094 }
1095 }
1096 c.version = {major: version.major, minor: version.minor};
1097 c.session.version = c.version;
1098 }
1099
1100 // if a session is set, resume it
1101 if(session !== null) {
1102 // resuming session, expect a ChangeCipherSpec next
1103 c.expect = CCC;
1104 c.session.resuming = true;
1105
1106 // get new client random
1107 c.session.sp.client_random = msg.random.bytes();
1108 } else {
1109 // not resuming, expect a Certificate or ClientKeyExchange
1110 c.expect = (c.verifyClient !== false) ? CCE : CKE;
1111 c.session.resuming = false;
1112
1113 // create new security parameters
1114 tls.createSecurityParameters(c, msg);
1115 }
1116
1117 // connection now open
1118 c.open = true;
1119
1120 // queue server hello
1121 tls.queue(c, tls.createRecord(c, {
1122 type: tls.ContentType.handshake,
1123 data: tls.createServerHello(c)
1124 }));
1125
1126 if(c.session.resuming) {
1127 // queue change cipher spec message
1128 tls.queue(c, tls.createRecord(c, {
1129 type: tls.ContentType.change_cipher_spec,
1130 data: tls.createChangeCipherSpec()
1131 }));
1132
1133 // create pending state
1134 c.state.pending = tls.createConnectionState(c);
1135
1136 // change current write state to pending write state
1137 c.state.current.write = c.state.pending.write;
1138
1139 // queue finished
1140 tls.queue(c, tls.createRecord(c, {
1141 type: tls.ContentType.handshake,
1142 data: tls.createFinished(c)
1143 }));
1144 } else {
1145 // queue server certificate
1146 tls.queue(c, tls.createRecord(c, {
1147 type: tls.ContentType.handshake,
1148 data: tls.createCertificate(c)
1149 }));
1150
1151 if(!c.fail) {
1152 // queue server key exchange
1153 tls.queue(c, tls.createRecord(c, {
1154 type: tls.ContentType.handshake,
1155 data: tls.createServerKeyExchange(c)
1156 }));
1157
1158 // request client certificate if set
1159 if(c.verifyClient !== false) {
1160 // queue certificate request
1161 tls.queue(c, tls.createRecord(c, {
1162 type: tls.ContentType.handshake,
1163 data: tls.createCertificateRequest(c)
1164 }));
1165 }
1166
1167 // queue server hello done
1168 tls.queue(c, tls.createRecord(c, {
1169 type: tls.ContentType.handshake,
1170 data: tls.createServerHelloDone(c)
1171 }));
1172 }
1173 }
1174
1175 // send records
1176 tls.flush(c);
1177
1178 // continue
1179 c.process();
1180};
1181
1182/**
1183 * Called when a client receives a Certificate record.
1184 *
1185 * When this message will be sent:
1186 * The server must send a certificate whenever the agreed-upon key exchange
1187 * method is not an anonymous one. This message will always immediately
1188 * follow the server hello message.
1189 *
1190 * Meaning of this message:
1191 * The certificate type must be appropriate for the selected cipher suite's
1192 * key exchange algorithm, and is generally an X.509v3 certificate. It must
1193 * contain a key which matches the key exchange method, as follows. Unless
1194 * otherwise specified, the signing algorithm for the certificate must be
1195 * the same as the algorithm for the certificate key. Unless otherwise
1196 * specified, the public key may be of any length.
1197 *
1198 * opaque ASN.1Cert<1..2^24-1>;
1199 * struct {
1200 * ASN.1Cert certificate_list<1..2^24-1>;
1201 * } Certificate;
1202 *
1203 * @param c the connection.
1204 * @param record the record.
1205 * @param length the length of the handshake message.
1206 */
1207tls.handleCertificate = function(c, record, length) {
1208 // minimum of 3 bytes in message
1209 if(length < 3) {
1210 return c.error(c, {
1211 message: 'Invalid Certificate message. Message too short.',
1212 send: true,
1213 alert: {
1214 level: tls.Alert.Level.fatal,
1215 description: tls.Alert.Description.illegal_parameter
1216 }
1217 });
1218 }
1219
1220 var b = record.fragment;
1221 var msg = {
1222 certificate_list: readVector(b, 3)
1223 };
1224
1225 /* The sender's certificate will be first in the list (chain), each
1226 subsequent one that follows will certify the previous one, but root
1227 certificates (self-signed) that specify the certificate authority may
1228 be omitted under the assumption that clients must already possess it. */
1229 var cert, asn1;
1230 var certs = [];
1231 try {
1232 while(msg.certificate_list.length() > 0) {
1233 // each entry in msg.certificate_list is a vector with 3 len bytes
1234 cert = readVector(msg.certificate_list, 3);
1235 asn1 = forge.asn1.fromDer(cert);
1236 cert = forge.pki.certificateFromAsn1(asn1, true);
1237 certs.push(cert);
1238 }
1239 } catch(ex) {
1240 return c.error(c, {
1241 message: 'Could not parse certificate list.',
1242 cause: ex,
1243 send: true,
1244 alert: {
1245 level: tls.Alert.Level.fatal,
1246 description: tls.Alert.Description.bad_certificate
1247 }
1248 });
1249 }
1250
1251 // ensure at least 1 certificate was provided if in client-mode
1252 // or if verifyClient was set to true to require a certificate
1253 // (as opposed to 'optional')
1254 var client = (c.entity === tls.ConnectionEnd.client);
1255 if((client || c.verifyClient === true) && certs.length === 0) {
1256 // error, no certificate
1257 c.error(c, {
1258 message: client ?
1259 'No server certificate provided.' :
1260 'No client certificate provided.',
1261 send: true,
1262 alert: {
1263 level: tls.Alert.Level.fatal,
1264 description: tls.Alert.Description.illegal_parameter
1265 }
1266 });
1267 } else if(certs.length === 0) {
1268 // no certs to verify
1269 // expect a ServerKeyExchange or ClientKeyExchange message next
1270 c.expect = client ? SKE : CKE;
1271 } else {
1272 // save certificate in session
1273 if(client) {
1274 c.session.serverCertificate = certs[0];
1275 } else {
1276 c.session.clientCertificate = certs[0];
1277 }
1278
1279 if(tls.verifyCertificateChain(c, certs)) {
1280 // expect a ServerKeyExchange or ClientKeyExchange message next
1281 c.expect = client ? SKE : CKE;
1282 }
1283 }
1284
1285 // continue
1286 c.process();
1287};
1288
1289/**
1290 * Called when a client receives a ServerKeyExchange record.
1291 *
1292 * When this message will be sent:
1293 * This message will be sent immediately after the server certificate
1294 * message (or the server hello message, if this is an anonymous
1295 * negotiation).
1296 *
1297 * The server key exchange message is sent by the server only when the
1298 * server certificate message (if sent) does not contain enough data to
1299 * allow the client to exchange a premaster secret.
1300 *
1301 * Meaning of this message:
1302 * This message conveys cryptographic information to allow the client to
1303 * communicate the premaster secret: either an RSA public key to encrypt
1304 * the premaster secret with, or a Diffie-Hellman public key with which the
1305 * client can complete a key exchange (with the result being the premaster
1306 * secret.)
1307 *
1308 * enum {
1309 * dhe_dss, dhe_rsa, dh_anon, rsa, dh_dss, dh_rsa
1310 * } KeyExchangeAlgorithm;
1311 *
1312 * struct {
1313 * opaque dh_p<1..2^16-1>;
1314 * opaque dh_g<1..2^16-1>;
1315 * opaque dh_Ys<1..2^16-1>;
1316 * } ServerDHParams;
1317 *
1318 * struct {
1319 * select(KeyExchangeAlgorithm) {
1320 * case dh_anon:
1321 * ServerDHParams params;
1322 * case dhe_dss:
1323 * case dhe_rsa:
1324 * ServerDHParams params;
1325 * digitally-signed struct {
1326 * opaque client_random[32];
1327 * opaque server_random[32];
1328 * ServerDHParams params;
1329 * } signed_params;
1330 * case rsa:
1331 * case dh_dss:
1332 * case dh_rsa:
1333 * struct {};
1334 * };
1335 * } ServerKeyExchange;
1336 *
1337 * @param c the connection.
1338 * @param record the record.
1339 * @param length the length of the handshake message.
1340 */
1341tls.handleServerKeyExchange = function(c, record, length) {
1342 // this implementation only supports RSA, no Diffie-Hellman support
1343 // so any length > 0 is invalid
1344 if(length > 0) {
1345 return c.error(c, {
1346 message: 'Invalid key parameters. Only RSA is supported.',
1347 send: true,
1348 alert: {
1349 level: tls.Alert.Level.fatal,
1350 description: tls.Alert.Description.unsupported_certificate
1351 }
1352 });
1353 }
1354
1355 // expect an optional CertificateRequest message next
1356 c.expect = SCR;
1357
1358 // continue
1359 c.process();
1360};
1361
1362/**
1363 * Called when a client receives a ClientKeyExchange record.
1364 *
1365 * @param c the connection.
1366 * @param record the record.
1367 * @param length the length of the handshake message.
1368 */
1369tls.handleClientKeyExchange = function(c, record, length) {
1370 // this implementation only supports RSA, no Diffie-Hellman support
1371 // so any length < 48 is invalid
1372 if(length < 48) {
1373 return c.error(c, {
1374 message: 'Invalid key parameters. Only RSA is supported.',
1375 send: true,
1376 alert: {
1377 level: tls.Alert.Level.fatal,
1378 description: tls.Alert.Description.unsupported_certificate
1379 }
1380 });
1381 }
1382
1383 var b = record.fragment;
1384 var msg = {
1385 enc_pre_master_secret: readVector(b, 2).getBytes()
1386 };
1387
1388 // do rsa decryption
1389 var privateKey = null;
1390 if(c.getPrivateKey) {
1391 try {
1392 privateKey = c.getPrivateKey(c, c.session.serverCertificate);
1393 privateKey = forge.pki.privateKeyFromPem(privateKey);
1394 } catch(ex) {
1395 c.error(c, {
1396 message: 'Could not get private key.',
1397 cause: ex,
1398 send: true,
1399 alert: {
1400 level: tls.Alert.Level.fatal,
1401 description: tls.Alert.Description.internal_error
1402 }
1403 });
1404 }
1405 }
1406
1407 if(privateKey === null) {
1408 return c.error(c, {
1409 message: 'No private key set.',
1410 send: true,
1411 alert: {
1412 level: tls.Alert.Level.fatal,
1413 description: tls.Alert.Description.internal_error
1414 }
1415 });
1416 }
1417
1418 try {
1419 // decrypt 48-byte pre-master secret
1420 var sp = c.session.sp;
1421 sp.pre_master_secret = privateKey.decrypt(msg.enc_pre_master_secret);
1422
1423 // ensure client hello version matches first 2 bytes
1424 var version = c.session.clientHelloVersion;
1425 if(version.major !== sp.pre_master_secret.charCodeAt(0) ||
1426 version.minor !== sp.pre_master_secret.charCodeAt(1)) {
1427 // error, do not send alert (see BLEI attack below)
1428 throw new Error('TLS version rollback attack detected.');
1429 }
1430 } catch(ex) {
1431 /* Note: Daniel Bleichenbacher [BLEI] can be used to attack a
1432 TLS server which is using PKCS#1 encoded RSA, so instead of
1433 failing here, we generate 48 random bytes and use that as
1434 the pre-master secret. */
1435 sp.pre_master_secret = forge.random.getBytes(48);
1436 }
1437
1438 // expect a CertificateVerify message if a Certificate was received that
1439 // does not have fixed Diffie-Hellman params, otherwise expect
1440 // ChangeCipherSpec
1441 c.expect = CCC;
1442 if(c.session.clientCertificate !== null) {
1443 // only RSA support, so expect CertificateVerify
1444 // TODO: support Diffie-Hellman
1445 c.expect = CCV;
1446 }
1447
1448 // continue
1449 c.process();
1450};
1451
1452/**
1453 * Called when a client receives a CertificateRequest record.
1454 *
1455 * When this message will be sent:
1456 * A non-anonymous server can optionally request a certificate from the
1457 * client, if appropriate for the selected cipher suite. This message, if
1458 * sent, will immediately follow the Server Key Exchange message (if it is
1459 * sent; otherwise, the Server Certificate message).
1460 *
1461 * enum {
1462 * rsa_sign(1), dss_sign(2), rsa_fixed_dh(3), dss_fixed_dh(4),
1463 * rsa_ephemeral_dh_RESERVED(5), dss_ephemeral_dh_RESERVED(6),
1464 * fortezza_dms_RESERVED(20), (255)
1465 * } ClientCertificateType;
1466 *
1467 * opaque DistinguishedName<1..2^16-1>;
1468 *
1469 * struct {
1470 * ClientCertificateType certificate_types<1..2^8-1>;
1471 * SignatureAndHashAlgorithm supported_signature_algorithms<2^16-1>;
1472 * DistinguishedName certificate_authorities<0..2^16-1>;
1473 * } CertificateRequest;
1474 *
1475 * @param c the connection.
1476 * @param record the record.
1477 * @param length the length of the handshake message.
1478 */
1479tls.handleCertificateRequest = function(c, record, length) {
1480 // minimum of 3 bytes in message
1481 if(length < 3) {
1482 return c.error(c, {
1483 message: 'Invalid CertificateRequest. Message too short.',
1484 send: true,
1485 alert: {
1486 level: tls.Alert.Level.fatal,
1487 description: tls.Alert.Description.illegal_parameter
1488 }
1489 });
1490 }
1491
1492 // TODO: TLS 1.2+ has different format including
1493 // SignatureAndHashAlgorithm after cert types
1494 var b = record.fragment;
1495 var msg = {
1496 certificate_types: readVector(b, 1),
1497 certificate_authorities: readVector(b, 2)
1498 };
1499
1500 // save certificate request in session
1501 c.session.certificateRequest = msg;
1502
1503 // expect a ServerHelloDone message next
1504 c.expect = SHD;
1505
1506 // continue
1507 c.process();
1508};
1509
1510/**
1511 * Called when a server receives a CertificateVerify record.
1512 *
1513 * @param c the connection.
1514 * @param record the record.
1515 * @param length the length of the handshake message.
1516 */
1517tls.handleCertificateVerify = function(c, record, length) {
1518 if(length < 2) {
1519 return c.error(c, {
1520 message: 'Invalid CertificateVerify. Message too short.',
1521 send: true,
1522 alert: {
1523 level: tls.Alert.Level.fatal,
1524 description: tls.Alert.Description.illegal_parameter
1525 }
1526 });
1527 }
1528
1529 // rewind to get full bytes for message so it can be manually
1530 // digested below (special case for CertificateVerify messages because
1531 // they must be digested *after* handling as opposed to all others)
1532 var b = record.fragment;
1533 b.read -= 4;
1534 var msgBytes = b.bytes();
1535 b.read += 4;
1536
1537 var msg = {
1538 signature: readVector(b, 2).getBytes()
1539 };
1540
1541 // TODO: add support for DSA
1542
1543 // generate data to verify
1544 var verify = forge.util.createBuffer();
1545 verify.putBuffer(c.session.md5.digest());
1546 verify.putBuffer(c.session.sha1.digest());
1547 verify = verify.getBytes();
1548
1549 try {
1550 var cert = c.session.clientCertificate;
1551 /*b = forge.pki.rsa.decrypt(
1552 msg.signature, cert.publicKey, true, verify.length);
1553 if(b !== verify) {*/
1554 if(!cert.publicKey.verify(verify, msg.signature, 'NONE')) {
1555 throw new Error('CertificateVerify signature does not match.');
1556 }
1557
1558 // digest message now that it has been handled
1559 c.session.md5.update(msgBytes);
1560 c.session.sha1.update(msgBytes);
1561 } catch(ex) {
1562 return c.error(c, {
1563 message: 'Bad signature in CertificateVerify.',
1564 send: true,
1565 alert: {
1566 level: tls.Alert.Level.fatal,
1567 description: tls.Alert.Description.handshake_failure
1568 }
1569 });
1570 }
1571
1572 // expect ChangeCipherSpec
1573 c.expect = CCC;
1574
1575 // continue
1576 c.process();
1577};
1578
1579/**
1580 * Called when a client receives a ServerHelloDone record.
1581 *
1582 * When this message will be sent:
1583 * The server hello done message is sent by the server to indicate the end
1584 * of the server hello and associated messages. After sending this message
1585 * the server will wait for a client response.
1586 *
1587 * Meaning of this message:
1588 * This message means that the server is done sending messages to support
1589 * the key exchange, and the client can proceed with its phase of the key
1590 * exchange.
1591 *
1592 * Upon receipt of the server hello done message the client should verify
1593 * that the server provided a valid certificate if required and check that
1594 * the server hello parameters are acceptable.
1595 *
1596 * struct {} ServerHelloDone;
1597 *
1598 * @param c the connection.
1599 * @param record the record.
1600 * @param length the length of the handshake message.
1601 */
1602tls.handleServerHelloDone = function(c, record, length) {
1603 // len must be 0 bytes
1604 if(length > 0) {
1605 return c.error(c, {
1606 message: 'Invalid ServerHelloDone message. Invalid length.',
1607 send: true,
1608 alert: {
1609 level: tls.Alert.Level.fatal,
1610 description: tls.Alert.Description.record_overflow
1611 }
1612 });
1613 }
1614
1615 if(c.serverCertificate === null) {
1616 // no server certificate was provided
1617 var error = {
1618 message: 'No server certificate provided. Not enough security.',
1619 send: true,
1620 alert: {
1621 level: tls.Alert.Level.fatal,
1622 description: tls.Alert.Description.insufficient_security
1623 }
1624 };
1625
1626 // call application callback
1627 var depth = 0;
1628 var ret = c.verify(c, error.alert.description, depth, []);
1629 if(ret !== true) {
1630 // check for custom alert info
1631 if(ret || ret === 0) {
1632 // set custom message and alert description
1633 if(typeof ret === 'object' && !forge.util.isArray(ret)) {
1634 if(ret.message) {
1635 error.message = ret.message;
1636 }
1637 if(ret.alert) {
1638 error.alert.description = ret.alert;
1639 }
1640 } else if(typeof ret === 'number') {
1641 // set custom alert description
1642 error.alert.description = ret;
1643 }
1644 }
1645
1646 // send error
1647 return c.error(c, error);
1648 }
1649 }
1650
1651 // create client certificate message if requested
1652 if(c.session.certificateRequest !== null) {
1653 record = tls.createRecord(c, {
1654 type: tls.ContentType.handshake,
1655 data: tls.createCertificate(c)
1656 });
1657 tls.queue(c, record);
1658 }
1659
1660 // create client key exchange message
1661 record = tls.createRecord(c, {
1662 type: tls.ContentType.handshake,
1663 data: tls.createClientKeyExchange(c)
1664 });
1665 tls.queue(c, record);
1666
1667 // expect no messages until the following callback has been called
1668 c.expect = SER;
1669
1670 // create callback to handle client signature (for client-certs)
1671 var callback = function(c, signature) {
1672 if(c.session.certificateRequest !== null &&
1673 c.session.clientCertificate !== null) {
1674 // create certificate verify message
1675 tls.queue(c, tls.createRecord(c, {
1676 type: tls.ContentType.handshake,
1677 data: tls.createCertificateVerify(c, signature)
1678 }));
1679 }
1680
1681 // create change cipher spec message
1682 tls.queue(c, tls.createRecord(c, {
1683 type: tls.ContentType.change_cipher_spec,
1684 data: tls.createChangeCipherSpec()
1685 }));
1686
1687 // create pending state
1688 c.state.pending = tls.createConnectionState(c);
1689
1690 // change current write state to pending write state
1691 c.state.current.write = c.state.pending.write;
1692
1693 // create finished message
1694 tls.queue(c, tls.createRecord(c, {
1695 type: tls.ContentType.handshake,
1696 data: tls.createFinished(c)
1697 }));
1698
1699 // expect a server ChangeCipherSpec message next
1700 c.expect = SCC;
1701
1702 // send records
1703 tls.flush(c);
1704
1705 // continue
1706 c.process();
1707 };
1708
1709 // if there is no certificate request or no client certificate, do
1710 // callback immediately
1711 if(c.session.certificateRequest === null ||
1712 c.session.clientCertificate === null) {
1713 return callback(c, null);
1714 }
1715
1716 // otherwise get the client signature
1717 tls.getClientSignature(c, callback);
1718};
1719
1720/**
1721 * Called when a ChangeCipherSpec record is received.
1722 *
1723 * @param c the connection.
1724 * @param record the record.
1725 */
1726tls.handleChangeCipherSpec = function(c, record) {
1727 if(record.fragment.getByte() !== 0x01) {
1728 return c.error(c, {
1729 message: 'Invalid ChangeCipherSpec message received.',
1730 send: true,
1731 alert: {
1732 level: tls.Alert.Level.fatal,
1733 description: tls.Alert.Description.illegal_parameter
1734 }
1735 });
1736 }
1737
1738 // create pending state if:
1739 // 1. Resuming session in client mode OR
1740 // 2. NOT resuming session in server mode
1741 var client = (c.entity === tls.ConnectionEnd.client);
1742 if((c.session.resuming && client) || (!c.session.resuming && !client)) {
1743 c.state.pending = tls.createConnectionState(c);
1744 }
1745
1746 // change current read state to pending read state
1747 c.state.current.read = c.state.pending.read;
1748
1749 // clear pending state if:
1750 // 1. NOT resuming session in client mode OR
1751 // 2. resuming a session in server mode
1752 if((!c.session.resuming && client) || (c.session.resuming && !client)) {
1753 c.state.pending = null;
1754 }
1755
1756 // expect a Finished record next
1757 c.expect = client ? SFI : CFI;
1758
1759 // continue
1760 c.process();
1761};
1762
1763/**
1764 * Called when a Finished record is received.
1765 *
1766 * When this message will be sent:
1767 * A finished message is always sent immediately after a change
1768 * cipher spec message to verify that the key exchange and
1769 * authentication processes were successful. It is essential that a
1770 * change cipher spec message be received between the other
1771 * handshake messages and the Finished message.
1772 *
1773 * Meaning of this message:
1774 * The finished message is the first protected with the just-
1775 * negotiated algorithms, keys, and secrets. Recipients of finished
1776 * messages must verify that the contents are correct. Once a side
1777 * has sent its Finished message and received and validated the
1778 * Finished message from its peer, it may begin to send and receive
1779 * application data over the connection.
1780 *
1781 * struct {
1782 * opaque verify_data[verify_data_length];
1783 * } Finished;
1784 *
1785 * verify_data
1786 * PRF(master_secret, finished_label, Hash(handshake_messages))
1787 * [0..verify_data_length-1];
1788 *
1789 * finished_label
1790 * For Finished messages sent by the client, the string
1791 * "client finished". For Finished messages sent by the server, the
1792 * string "server finished".
1793 *
1794 * verify_data_length depends on the cipher suite. If it is not specified
1795 * by the cipher suite, then it is 12. Versions of TLS < 1.2 always used
1796 * 12 bytes.
1797 *
1798 * @param c the connection.
1799 * @param record the record.
1800 * @param length the length of the handshake message.
1801 */
1802tls.handleFinished = function(c, record, length) {
1803 // rewind to get full bytes for message so it can be manually
1804 // digested below (special case for Finished messages because they
1805 // must be digested *after* handling as opposed to all others)
1806 var b = record.fragment;
1807 b.read -= 4;
1808 var msgBytes = b.bytes();
1809 b.read += 4;
1810
1811 // message contains only verify_data
1812 var vd = record.fragment.getBytes();
1813
1814 // ensure verify data is correct
1815 b = forge.util.createBuffer();
1816 b.putBuffer(c.session.md5.digest());
1817 b.putBuffer(c.session.sha1.digest());
1818
1819 // set label based on entity type
1820 var client = (c.entity === tls.ConnectionEnd.client);
1821 var label = client ? 'server finished' : 'client finished';
1822
1823 // TODO: determine prf function and verify length for TLS 1.2
1824 var sp = c.session.sp;
1825 var vdl = 12;
1826 var prf = prf_TLS1;
1827 b = prf(sp.master_secret, label, b.getBytes(), vdl);
1828 if(b.getBytes() !== vd) {
1829 return c.error(c, {
1830 message: 'Invalid verify_data in Finished message.',
1831 send: true,
1832 alert: {
1833 level: tls.Alert.Level.fatal,
1834 description: tls.Alert.Description.decrypt_error
1835 }
1836 });
1837 }
1838
1839 // digest finished message now that it has been handled
1840 c.session.md5.update(msgBytes);
1841 c.session.sha1.update(msgBytes);
1842
1843 // resuming session as client or NOT resuming session as server
1844 if((c.session.resuming && client) || (!c.session.resuming && !client)) {
1845 // create change cipher spec message
1846 tls.queue(c, tls.createRecord(c, {
1847 type: tls.ContentType.change_cipher_spec,
1848 data: tls.createChangeCipherSpec()
1849 }));
1850
1851 // change current write state to pending write state, clear pending
1852 c.state.current.write = c.state.pending.write;
1853 c.state.pending = null;
1854
1855 // create finished message
1856 tls.queue(c, tls.createRecord(c, {
1857 type: tls.ContentType.handshake,
1858 data: tls.createFinished(c)
1859 }));
1860 }
1861
1862 // expect application data next
1863 c.expect = client ? SAD : CAD;
1864
1865 // handshake complete
1866 c.handshaking = false;
1867 ++c.handshakes;
1868
1869 // save access to peer certificate
1870 c.peerCertificate = client ?
1871 c.session.serverCertificate : c.session.clientCertificate;
1872
1873 // send records
1874 tls.flush(c);
1875
1876 // now connected
1877 c.isConnected = true;
1878 c.connected(c);
1879
1880 // continue
1881 c.process();
1882};
1883
1884/**
1885 * Called when an Alert record is received.
1886 *
1887 * @param c the connection.
1888 * @param record the record.
1889 */
1890tls.handleAlert = function(c, record) {
1891 // read alert
1892 var b = record.fragment;
1893 var alert = {
1894 level: b.getByte(),
1895 description: b.getByte()
1896 };
1897
1898 // TODO: consider using a table?
1899 // get appropriate message
1900 var msg;
1901 switch(alert.description) {
1902 case tls.Alert.Description.close_notify:
1903 msg = 'Connection closed.';
1904 break;
1905 case tls.Alert.Description.unexpected_message:
1906 msg = 'Unexpected message.';
1907 break;
1908 case tls.Alert.Description.bad_record_mac:
1909 msg = 'Bad record MAC.';
1910 break;
1911 case tls.Alert.Description.decryption_failed:
1912 msg = 'Decryption failed.';
1913 break;
1914 case tls.Alert.Description.record_overflow:
1915 msg = 'Record overflow.';
1916 break;
1917 case tls.Alert.Description.decompression_failure:
1918 msg = 'Decompression failed.';
1919 break;
1920 case tls.Alert.Description.handshake_failure:
1921 msg = 'Handshake failure.';
1922 break;
1923 case tls.Alert.Description.bad_certificate:
1924 msg = 'Bad certificate.';
1925 break;
1926 case tls.Alert.Description.unsupported_certificate:
1927 msg = 'Unsupported certificate.';
1928 break;
1929 case tls.Alert.Description.certificate_revoked:
1930 msg = 'Certificate revoked.';
1931 break;
1932 case tls.Alert.Description.certificate_expired:
1933 msg = 'Certificate expired.';
1934 break;
1935 case tls.Alert.Description.certificate_unknown:
1936 msg = 'Certificate unknown.';
1937 break;
1938 case tls.Alert.Description.illegal_parameter:
1939 msg = 'Illegal parameter.';
1940 break;
1941 case tls.Alert.Description.unknown_ca:
1942 msg = 'Unknown certificate authority.';
1943 break;
1944 case tls.Alert.Description.access_denied:
1945 msg = 'Access denied.';
1946 break;
1947 case tls.Alert.Description.decode_error:
1948 msg = 'Decode error.';
1949 break;
1950 case tls.Alert.Description.decrypt_error:
1951 msg = 'Decrypt error.';
1952 break;
1953 case tls.Alert.Description.export_restriction:
1954 msg = 'Export restriction.';
1955 break;
1956 case tls.Alert.Description.protocol_version:
1957 msg = 'Unsupported protocol version.';
1958 break;
1959 case tls.Alert.Description.insufficient_security:
1960 msg = 'Insufficient security.';
1961 break;
1962 case tls.Alert.Description.internal_error:
1963 msg = 'Internal error.';
1964 break;
1965 case tls.Alert.Description.user_canceled:
1966 msg = 'User canceled.';
1967 break;
1968 case tls.Alert.Description.no_renegotiation:
1969 msg = 'Renegotiation not supported.';
1970 break;
1971 default:
1972 msg = 'Unknown error.';
1973 break;
1974 }
1975
1976 // close connection on close_notify, not an error
1977 if(alert.description === tls.Alert.Description.close_notify) {
1978 return c.close();
1979 }
1980
1981 // call error handler
1982 c.error(c, {
1983 message: msg,
1984 send: false,
1985 // origin is the opposite end
1986 origin: (c.entity === tls.ConnectionEnd.client) ? 'server' : 'client',
1987 alert: alert
1988 });
1989
1990 // continue
1991 c.process();
1992};
1993
1994/**
1995 * Called when a Handshake record is received.
1996 *
1997 * @param c the connection.
1998 * @param record the record.
1999 */
2000tls.handleHandshake = function(c, record) {
2001 // get the handshake type and message length
2002 var b = record.fragment;
2003 var type = b.getByte();
2004 var length = b.getInt24();
2005
2006 // see if the record fragment doesn't yet contain the full message
2007 if(length > b.length()) {
2008 // cache the record, clear its fragment, and reset the buffer read
2009 // pointer before the type and length were read
2010 c.fragmented = record;
2011 record.fragment = forge.util.createBuffer();
2012 b.read -= 4;
2013
2014 // continue
2015 return c.process();
2016 }
2017
2018 // full message now available, clear cache, reset read pointer to
2019 // before type and length
2020 c.fragmented = null;
2021 b.read -= 4;
2022
2023 // save the handshake bytes for digestion after handler is found
2024 // (include type and length of handshake msg)
2025 var bytes = b.bytes(length + 4);
2026
2027 // restore read pointer
2028 b.read += 4;
2029
2030 // handle expected message
2031 if(type in hsTable[c.entity][c.expect]) {
2032 // initialize server session
2033 if(c.entity === tls.ConnectionEnd.server && !c.open && !c.fail) {
2034 c.handshaking = true;
2035 c.session = {
2036 version: null,
2037 extensions: {
2038 server_name: {
2039 serverNameList: []
2040 }
2041 },
2042 cipherSuite: null,
2043 compressionMethod: null,
2044 serverCertificate: null,
2045 clientCertificate: null,
2046 md5: forge.md.md5.create(),
2047 sha1: forge.md.sha1.create()
2048 };
2049 }
2050
2051 /* Update handshake messages digest. Finished and CertificateVerify
2052 messages are not digested here. They can't be digested as part of
2053 the verify_data that they contain. These messages are manually
2054 digested in their handlers. HelloRequest messages are simply never
2055 included in the handshake message digest according to spec. */
2056 if(type !== tls.HandshakeType.hello_request &&
2057 type !== tls.HandshakeType.certificate_verify &&
2058 type !== tls.HandshakeType.finished) {
2059 c.session.md5.update(bytes);
2060 c.session.sha1.update(bytes);
2061 }
2062
2063 // handle specific handshake type record
2064 hsTable[c.entity][c.expect][type](c, record, length);
2065 } else {
2066 // unexpected record
2067 tls.handleUnexpected(c, record);
2068 }
2069};
2070
2071/**
2072 * Called when an ApplicationData record is received.
2073 *
2074 * @param c the connection.
2075 * @param record the record.
2076 */
2077tls.handleApplicationData = function(c, record) {
2078 // buffer data, notify that its ready
2079 c.data.putBuffer(record.fragment);
2080 c.dataReady(c);
2081
2082 // continue
2083 c.process();
2084};
2085
2086/**
2087 * Called when a Heartbeat record is received.
2088 *
2089 * @param c the connection.
2090 * @param record the record.
2091 */
2092tls.handleHeartbeat = function(c, record) {
2093 // get the heartbeat type and payload
2094 var b = record.fragment;
2095 var type = b.getByte();
2096 var length = b.getInt16();
2097 var payload = b.getBytes(length);
2098
2099 if(type === tls.HeartbeatMessageType.heartbeat_request) {
2100 // discard request during handshake or if length is too large
2101 if(c.handshaking || length > payload.length) {
2102 // continue
2103 return c.process();
2104 }
2105 // retransmit payload
2106 tls.queue(c, tls.createRecord(c, {
2107 type: tls.ContentType.heartbeat,
2108 data: tls.createHeartbeat(
2109 tls.HeartbeatMessageType.heartbeat_response, payload)
2110 }));
2111 tls.flush(c);
2112 } else if(type === tls.HeartbeatMessageType.heartbeat_response) {
2113 // check payload against expected payload, discard heartbeat if no match
2114 if(payload !== c.expectedHeartbeatPayload) {
2115 // continue
2116 return c.process();
2117 }
2118
2119 // notify that a valid heartbeat was received
2120 if(c.heartbeatReceived) {
2121 c.heartbeatReceived(c, forge.util.createBuffer(payload));
2122 }
2123 }
2124
2125 // continue
2126 c.process();
2127};
2128
2129/**
2130 * The transistional state tables for receiving TLS records. It maps the
2131 * current TLS engine state and a received record to a function to handle the
2132 * record and update the state.
2133 *
2134 * For instance, if the current state is SHE, then the TLS engine is expecting
2135 * a ServerHello record. Once a record is received, the handler function is
2136 * looked up using the state SHE and the record's content type.
2137 *
2138 * The resulting function will either be an error handler or a record handler.
2139 * The function will take whatever action is appropriate and update the state
2140 * for the next record.
2141 *
2142 * The states are all based on possible server record types. Note that the
2143 * client will never specifically expect to receive a HelloRequest or an alert
2144 * from the server so there is no state that reflects this. These messages may
2145 * occur at any time.
2146 *
2147 * There are two tables for mapping states because there is a second tier of
2148 * types for handshake messages. Once a record with a content type of handshake
2149 * is received, the handshake record handler will look up the handshake type in
2150 * the secondary map to get its appropriate handler.
2151 *
2152 * Valid message orders are as follows:
2153 *
2154 * =======================FULL HANDSHAKE======================
2155 * Client Server
2156 *
2157 * ClientHello -------->
2158 * ServerHello
2159 * Certificate*
2160 * ServerKeyExchange*
2161 * CertificateRequest*
2162 * <-------- ServerHelloDone
2163 * Certificate*
2164 * ClientKeyExchange
2165 * CertificateVerify*
2166 * [ChangeCipherSpec]
2167 * Finished -------->
2168 * [ChangeCipherSpec]
2169 * <-------- Finished
2170 * Application Data <-------> Application Data
2171 *
2172 * =====================SESSION RESUMPTION=====================
2173 * Client Server
2174 *
2175 * ClientHello -------->
2176 * ServerHello
2177 * [ChangeCipherSpec]
2178 * <-------- Finished
2179 * [ChangeCipherSpec]
2180 * Finished -------->
2181 * Application Data <-------> Application Data
2182 */
2183// client expect states (indicate which records are expected to be received)
2184var SHE = 0; // rcv server hello
2185var SCE = 1; // rcv server certificate
2186var SKE = 2; // rcv server key exchange
2187var SCR = 3; // rcv certificate request
2188var SHD = 4; // rcv server hello done
2189var SCC = 5; // rcv change cipher spec
2190var SFI = 6; // rcv finished
2191var SAD = 7; // rcv application data
2192var SER = 8; // not expecting any messages at this point
2193
2194// server expect states
2195var CHE = 0; // rcv client hello
2196var CCE = 1; // rcv client certificate
2197var CKE = 2; // rcv client key exchange
2198var CCV = 3; // rcv certificate verify
2199var CCC = 4; // rcv change cipher spec
2200var CFI = 5; // rcv finished
2201var CAD = 6; // rcv application data
2202var CER = 7; // not expecting any messages at this point
2203
2204// map client current expect state and content type to function
2205var __ = tls.handleUnexpected;
2206var R0 = tls.handleChangeCipherSpec;
2207var R1 = tls.handleAlert;
2208var R2 = tls.handleHandshake;
2209var R3 = tls.handleApplicationData;
2210var R4 = tls.handleHeartbeat;
2211var ctTable = [];
2212ctTable[tls.ConnectionEnd.client] = [
2213// CC,AL,HS,AD,HB
2214/*SHE*/[__,R1,R2,__,R4],
2215/*SCE*/[__,R1,R2,__,R4],
2216/*SKE*/[__,R1,R2,__,R4],
2217/*SCR*/[__,R1,R2,__,R4],
2218/*SHD*/[__,R1,R2,__,R4],
2219/*SCC*/[R0,R1,__,__,R4],
2220/*SFI*/[__,R1,R2,__,R4],
2221/*SAD*/[__,R1,R2,R3,R4],
2222/*SER*/[__,R1,R2,__,R4]
2223];
2224
2225// map server current expect state and content type to function
2226ctTable[tls.ConnectionEnd.server] = [
2227// CC,AL,HS,AD
2228/*CHE*/[__,R1,R2,__,R4],
2229/*CCE*/[__,R1,R2,__,R4],
2230/*CKE*/[__,R1,R2,__,R4],
2231/*CCV*/[__,R1,R2,__,R4],
2232/*CCC*/[R0,R1,__,__,R4],
2233/*CFI*/[__,R1,R2,__,R4],
2234/*CAD*/[__,R1,R2,R3,R4],
2235/*CER*/[__,R1,R2,__,R4]
2236];
2237
2238// map client current expect state and handshake type to function
2239var H0 = tls.handleHelloRequest;
2240var H1 = tls.handleServerHello;
2241var H2 = tls.handleCertificate;
2242var H3 = tls.handleServerKeyExchange;
2243var H4 = tls.handleCertificateRequest;
2244var H5 = tls.handleServerHelloDone;
2245var H6 = tls.handleFinished;
2246var hsTable = [];
2247hsTable[tls.ConnectionEnd.client] = [
2248// HR,01,SH,03,04,05,06,07,08,09,10,SC,SK,CR,HD,15,CK,17,18,19,FI
2249/*SHE*/[__,__,H1,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__],
2250/*SCE*/[H0,__,__,__,__,__,__,__,__,__,__,H2,H3,H4,H5,__,__,__,__,__,__],
2251/*SKE*/[H0,__,__,__,__,__,__,__,__,__,__,__,H3,H4,H5,__,__,__,__,__,__],
2252/*SCR*/[H0,__,__,__,__,__,__,__,__,__,__,__,__,H4,H5,__,__,__,__,__,__],
2253/*SHD*/[H0,__,__,__,__,__,__,__,__,__,__,__,__,__,H5,__,__,__,__,__,__],
2254/*SCC*/[H0,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__],
2255/*SFI*/[H0,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,H6],
2256/*SAD*/[H0,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__],
2257/*SER*/[H0,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__]
2258];
2259
2260// map server current expect state and handshake type to function
2261// Note: CAD[CH] does not map to FB because renegotation is prohibited
2262var H7 = tls.handleClientHello;
2263var H8 = tls.handleClientKeyExchange;
2264var H9 = tls.handleCertificateVerify;
2265hsTable[tls.ConnectionEnd.server] = [
2266// 01,CH,02,03,04,05,06,07,08,09,10,CC,12,13,14,CV,CK,17,18,19,FI
2267/*CHE*/[__,H7,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__],
2268/*CCE*/[__,__,__,__,__,__,__,__,__,__,__,H2,__,__,__,__,__,__,__,__,__],
2269/*CKE*/[__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,H8,__,__,__,__],
2270/*CCV*/[__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,H9,__,__,__,__,__],
2271/*CCC*/[__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__],
2272/*CFI*/[__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,H6],
2273/*CAD*/[__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__],
2274/*CER*/[__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__,__]
2275];
2276
2277/**
2278 * Generates the master_secret and keys using the given security parameters.
2279 *
2280 * The security parameters for a TLS connection state are defined as such:
2281 *
2282 * struct {
2283 * ConnectionEnd entity;
2284 * PRFAlgorithm prf_algorithm;
2285 * BulkCipherAlgorithm bulk_cipher_algorithm;
2286 * CipherType cipher_type;
2287 * uint8 enc_key_length;
2288 * uint8 block_length;
2289 * uint8 fixed_iv_length;
2290 * uint8 record_iv_length;
2291 * MACAlgorithm mac_algorithm;
2292 * uint8 mac_length;
2293 * uint8 mac_key_length;
2294 * CompressionMethod compression_algorithm;
2295 * opaque master_secret[48];
2296 * opaque client_random[32];
2297 * opaque server_random[32];
2298 * } SecurityParameters;
2299 *
2300 * Note that this definition is from TLS 1.2. In TLS 1.0 some of these
2301 * parameters are ignored because, for instance, the PRFAlgorithm is a
2302 * builtin-fixed algorithm combining iterations of MD5 and SHA-1 in TLS 1.0.
2303 *
2304 * The Record Protocol requires an algorithm to generate keys required by the
2305 * current connection state.
2306 *
2307 * The master secret is expanded into a sequence of secure bytes, which is then
2308 * split to a client write MAC key, a server write MAC key, a client write
2309 * encryption key, and a server write encryption key. In TLS 1.0 a client write
2310 * IV and server write IV are also generated. Each of these is generated from
2311 * the byte sequence in that order. Unused values are empty. In TLS 1.2, some
2312 * AEAD ciphers may additionally require a client write IV and a server write
2313 * IV (see Section 6.2.3.3).
2314 *
2315 * When keys, MAC keys, and IVs are generated, the master secret is used as an
2316 * entropy source.
2317 *
2318 * To generate the key material, compute:
2319 *
2320 * master_secret = PRF(pre_master_secret, "master secret",
2321 * ClientHello.random + ServerHello.random)
2322 *
2323 * key_block = PRF(SecurityParameters.master_secret,
2324 * "key expansion",
2325 * SecurityParameters.server_random +
2326 * SecurityParameters.client_random);
2327 *
2328 * until enough output has been generated. Then, the key_block is
2329 * partitioned as follows:
2330 *
2331 * client_write_MAC_key[SecurityParameters.mac_key_length]
2332 * server_write_MAC_key[SecurityParameters.mac_key_length]
2333 * client_write_key[SecurityParameters.enc_key_length]
2334 * server_write_key[SecurityParameters.enc_key_length]
2335 * client_write_IV[SecurityParameters.fixed_iv_length]
2336 * server_write_IV[SecurityParameters.fixed_iv_length]
2337 *
2338 * In TLS 1.2, the client_write_IV and server_write_IV are only generated for
2339 * implicit nonce techniques as described in Section 3.2.1 of [AEAD]. This
2340 * implementation uses TLS 1.0 so IVs are generated.
2341 *
2342 * Implementation note: The currently defined cipher suite which requires the
2343 * most material is AES_256_CBC_SHA256. It requires 2 x 32 byte keys and 2 x 32
2344 * byte MAC keys, for a total 128 bytes of key material. In TLS 1.0 it also
2345 * requires 2 x 16 byte IVs, so it actually takes 160 bytes of key material.
2346 *
2347 * @param c the connection.
2348 * @param sp the security parameters to use.
2349 *
2350 * @return the security keys.
2351 */
2352tls.generateKeys = function(c, sp) {
2353 // TLS_RSA_WITH_AES_128_CBC_SHA (required to be compliant with TLS 1.2) &
2354 // TLS_RSA_WITH_AES_256_CBC_SHA are the only cipher suites implemented
2355 // at present
2356
2357 // TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA is required to be compliant with
2358 // TLS 1.0 but we don't care right now because AES is better and we have
2359 // an implementation for it
2360
2361 // TODO: TLS 1.2 implementation
2362 /*
2363 // determine the PRF
2364 var prf;
2365 switch(sp.prf_algorithm) {
2366 case tls.PRFAlgorithm.tls_prf_sha256:
2367 prf = prf_sha256;
2368 break;
2369 default:
2370 // should never happen
2371 throw new Error('Invalid PRF');
2372 }
2373 */
2374
2375 // TLS 1.0/1.1 implementation
2376 var prf = prf_TLS1;
2377
2378 // concatenate server and client random
2379 var random = sp.client_random + sp.server_random;
2380
2381 // only create master secret if session is new
2382 if(!c.session.resuming) {
2383 // create master secret, clean up pre-master secret
2384 sp.master_secret = prf(
2385 sp.pre_master_secret, 'master secret', random, 48).bytes();
2386 sp.pre_master_secret = null;
2387 }
2388
2389 // generate the amount of key material needed
2390 random = sp.server_random + sp.client_random;
2391 var length = 2 * sp.mac_key_length + 2 * sp.enc_key_length;
2392
2393 // include IV for TLS/1.0
2394 var tls10 = (c.version.major === tls.Versions.TLS_1_0.major &&
2395 c.version.minor === tls.Versions.TLS_1_0.minor);
2396 if(tls10) {
2397 length += 2 * sp.fixed_iv_length;
2398 }
2399 var km = prf(sp.master_secret, 'key expansion', random, length);
2400
2401 // split the key material into the MAC and encryption keys
2402 var rval = {
2403 client_write_MAC_key: km.getBytes(sp.mac_key_length),
2404 server_write_MAC_key: km.getBytes(sp.mac_key_length),
2405 client_write_key: km.getBytes(sp.enc_key_length),
2406 server_write_key: km.getBytes(sp.enc_key_length)
2407 };
2408
2409 // include TLS 1.0 IVs
2410 if(tls10) {
2411 rval.client_write_IV = km.getBytes(sp.fixed_iv_length);
2412 rval.server_write_IV = km.getBytes(sp.fixed_iv_length);
2413 }
2414
2415 return rval;
2416};
2417
2418/**
2419 * Creates a new initialized TLS connection state. A connection state has
2420 * a read mode and a write mode.
2421 *
2422 * compression state:
2423 * The current state of the compression algorithm.
2424 *
2425 * cipher state:
2426 * The current state of the encryption algorithm. This will consist of the
2427 * scheduled key for that connection. For stream ciphers, this will also
2428 * contain whatever state information is necessary to allow the stream to
2429 * continue to encrypt or decrypt data.
2430 *
2431 * MAC key:
2432 * The MAC key for the connection.
2433 *
2434 * sequence number:
2435 * Each connection state contains a sequence number, which is maintained
2436 * separately for read and write states. The sequence number MUST be set to
2437 * zero whenever a connection state is made the active state. Sequence
2438 * numbers are of type uint64 and may not exceed 2^64-1. Sequence numbers do
2439 * not wrap. If a TLS implementation would need to wrap a sequence number,
2440 * it must renegotiate instead. A sequence number is incremented after each
2441 * record: specifically, the first record transmitted under a particular
2442 * connection state MUST use sequence number 0.
2443 *
2444 * @param c the connection.
2445 *
2446 * @return the new initialized TLS connection state.
2447 */
2448tls.createConnectionState = function(c) {
2449 var client = (c.entity === tls.ConnectionEnd.client);
2450
2451 var createMode = function() {
2452 var mode = {
2453 // two 32-bit numbers, first is most significant
2454 sequenceNumber: [0, 0],
2455 macKey: null,
2456 macLength: 0,
2457 macFunction: null,
2458 cipherState: null,
2459 cipherFunction: function(record) {return true;},
2460 compressionState: null,
2461 compressFunction: function(record) {return true;},
2462 updateSequenceNumber: function() {
2463 if(mode.sequenceNumber[1] === 0xFFFFFFFF) {
2464 mode.sequenceNumber[1] = 0;
2465 ++mode.sequenceNumber[0];
2466 } else {
2467 ++mode.sequenceNumber[1];
2468 }
2469 }
2470 };
2471 return mode;
2472 };
2473 var state = {
2474 read: createMode(),
2475 write: createMode()
2476 };
2477
2478 // update function in read mode will decrypt then decompress a record
2479 state.read.update = function(c, record) {
2480 if(!state.read.cipherFunction(record, state.read)) {
2481 c.error(c, {
2482 message: 'Could not decrypt record or bad MAC.',
2483 send: true,
2484 alert: {
2485 level: tls.Alert.Level.fatal,
2486 // doesn't matter if decryption failed or MAC was
2487 // invalid, return the same error so as not to reveal
2488 // which one occurred
2489 description: tls.Alert.Description.bad_record_mac
2490 }
2491 });
2492 } else if(!state.read.compressFunction(c, record, state.read)) {
2493 c.error(c, {
2494 message: 'Could not decompress record.',
2495 send: true,
2496 alert: {
2497 level: tls.Alert.Level.fatal,
2498 description: tls.Alert.Description.decompression_failure
2499 }
2500 });
2501 }
2502 return !c.fail;
2503 };
2504
2505 // update function in write mode will compress then encrypt a record
2506 state.write.update = function(c, record) {
2507 if(!state.write.compressFunction(c, record, state.write)) {
2508 // error, but do not send alert since it would require
2509 // compression as well
2510 c.error(c, {
2511 message: 'Could not compress record.',
2512 send: false,
2513 alert: {
2514 level: tls.Alert.Level.fatal,
2515 description: tls.Alert.Description.internal_error
2516 }
2517 });
2518 } else if(!state.write.cipherFunction(record, state.write)) {
2519 // error, but do not send alert since it would require
2520 // encryption as well
2521 c.error(c, {
2522 message: 'Could not encrypt record.',
2523 send: false,
2524 alert: {
2525 level: tls.Alert.Level.fatal,
2526 description: tls.Alert.Description.internal_error
2527 }
2528 });
2529 }
2530 return !c.fail;
2531 };
2532
2533 // handle security parameters
2534 if(c.session) {
2535 var sp = c.session.sp;
2536 c.session.cipherSuite.initSecurityParameters(sp);
2537
2538 // generate keys
2539 sp.keys = tls.generateKeys(c, sp);
2540 state.read.macKey = client ?
2541 sp.keys.server_write_MAC_key : sp.keys.client_write_MAC_key;
2542 state.write.macKey = client ?
2543 sp.keys.client_write_MAC_key : sp.keys.server_write_MAC_key;
2544
2545 // cipher suite setup
2546 c.session.cipherSuite.initConnectionState(state, c, sp);
2547
2548 // compression setup
2549 switch(sp.compression_algorithm) {
2550 case tls.CompressionMethod.none:
2551 break;
2552 case tls.CompressionMethod.deflate:
2553 state.read.compressFunction = inflate;
2554 state.write.compressFunction = deflate;
2555 break;
2556 default:
2557 throw new Error('Unsupported compression algorithm.');
2558 }
2559 }
2560
2561 return state;
2562};
2563
2564/**
2565 * Creates a Random structure.
2566 *
2567 * struct {
2568 * uint32 gmt_unix_time;
2569 * opaque random_bytes[28];
2570 * } Random;
2571 *
2572 * gmt_unix_time:
2573 * The current time and date in standard UNIX 32-bit format (seconds since
2574 * the midnight starting Jan 1, 1970, UTC, ignoring leap seconds) according
2575 * to the sender's internal clock. Clocks are not required to be set
2576 * correctly by the basic TLS protocol; higher-level or application
2577 * protocols may define additional requirements. Note that, for historical
2578 * reasons, the data element is named using GMT, the predecessor of the
2579 * current worldwide time base, UTC.
2580 * random_bytes:
2581 * 28 bytes generated by a secure random number generator.
2582 *
2583 * @return the Random structure as a byte array.
2584 */
2585tls.createRandom = function() {
2586 // get UTC milliseconds
2587 var d = new Date();
2588 var utc = +d + d.getTimezoneOffset() * 60000;
2589 var rval = forge.util.createBuffer();
2590 rval.putInt32(utc);
2591 rval.putBytes(forge.random.getBytes(28));
2592 return rval;
2593};
2594
2595/**
2596 * Creates a TLS record with the given type and data.
2597 *
2598 * @param c the connection.
2599 * @param options:
2600 * type: the record type.
2601 * data: the plain text data in a byte buffer.
2602 *
2603 * @return the created record.
2604 */
2605tls.createRecord = function(c, options) {
2606 if(!options.data) {
2607 return null;
2608 }
2609 var record = {
2610 type: options.type,
2611 version: {
2612 major: c.version.major,
2613 minor: c.version.minor
2614 },
2615 length: options.data.length(),
2616 fragment: options.data
2617 };
2618 return record;
2619};
2620
2621/**
2622 * Creates a TLS alert record.
2623 *
2624 * @param c the connection.
2625 * @param alert:
2626 * level: the TLS alert level.
2627 * description: the TLS alert description.
2628 *
2629 * @return the created alert record.
2630 */
2631tls.createAlert = function(c, alert) {
2632 var b = forge.util.createBuffer();
2633 b.putByte(alert.level);
2634 b.putByte(alert.description);
2635 return tls.createRecord(c, {
2636 type: tls.ContentType.alert,
2637 data: b
2638 });
2639};
2640
2641/* The structure of a TLS handshake message.
2642 *
2643 * struct {
2644 * HandshakeType msg_type; // handshake type
2645 * uint24 length; // bytes in message
2646 * select(HandshakeType) {
2647 * case hello_request: HelloRequest;
2648 * case client_hello: ClientHello;
2649 * case server_hello: ServerHello;
2650 * case certificate: Certificate;
2651 * case server_key_exchange: ServerKeyExchange;
2652 * case certificate_request: CertificateRequest;
2653 * case server_hello_done: ServerHelloDone;
2654 * case certificate_verify: CertificateVerify;
2655 * case client_key_exchange: ClientKeyExchange;
2656 * case finished: Finished;
2657 * } body;
2658 * } Handshake;
2659 */
2660
2661/**
2662 * Creates a ClientHello message.
2663 *
2664 * opaque SessionID<0..32>;
2665 * enum { null(0), deflate(1), (255) } CompressionMethod;
2666 * uint8 CipherSuite[2];
2667 *
2668 * struct {
2669 * ProtocolVersion client_version;
2670 * Random random;
2671 * SessionID session_id;
2672 * CipherSuite cipher_suites<2..2^16-2>;
2673 * CompressionMethod compression_methods<1..2^8-1>;
2674 * select(extensions_present) {
2675 * case false:
2676 * struct {};
2677 * case true:
2678 * Extension extensions<0..2^16-1>;
2679 * };
2680 * } ClientHello;
2681 *
2682 * The extension format for extended client hellos and server hellos is:
2683 *
2684 * struct {
2685 * ExtensionType extension_type;
2686 * opaque extension_data<0..2^16-1>;
2687 * } Extension;
2688 *
2689 * Here:
2690 *
2691 * - "extension_type" identifies the particular extension type.
2692 * - "extension_data" contains information specific to the particular
2693 * extension type.
2694 *
2695 * The extension types defined in this document are:
2696 *
2697 * enum {
2698 * server_name(0), max_fragment_length(1),
2699 * client_certificate_url(2), trusted_ca_keys(3),
2700 * truncated_hmac(4), status_request(5), (65535)
2701 * } ExtensionType;
2702 *
2703 * @param c the connection.
2704 *
2705 * @return the ClientHello byte buffer.
2706 */
2707tls.createClientHello = function(c) {
2708 // save hello version
2709 c.session.clientHelloVersion = {
2710 major: c.version.major,
2711 minor: c.version.minor
2712 };
2713
2714 // create supported cipher suites
2715 var cipherSuites = forge.util.createBuffer();
2716 for(var i = 0; i < c.cipherSuites.length; ++i) {
2717 var cs = c.cipherSuites[i];
2718 cipherSuites.putByte(cs.id[0]);
2719 cipherSuites.putByte(cs.id[1]);
2720 }
2721 var cSuites = cipherSuites.length();
2722
2723 // create supported compression methods, null always supported, but
2724 // also support deflate if connection has inflate and deflate methods
2725 var compressionMethods = forge.util.createBuffer();
2726 compressionMethods.putByte(tls.CompressionMethod.none);
2727 // FIXME: deflate support disabled until issues with raw deflate data
2728 // without zlib headers are resolved
2729 /*
2730 if(c.inflate !== null && c.deflate !== null) {
2731 compressionMethods.putByte(tls.CompressionMethod.deflate);
2732 }
2733 */
2734 var cMethods = compressionMethods.length();
2735
2736 // create TLS SNI (server name indication) extension if virtual host
2737 // has been specified, see RFC 3546
2738 var extensions = forge.util.createBuffer();
2739 if(c.virtualHost) {
2740 // create extension struct
2741 var ext = forge.util.createBuffer();
2742 ext.putByte(0x00); // type server_name (ExtensionType is 2 bytes)
2743 ext.putByte(0x00);
2744
2745 /* In order to provide the server name, clients MAY include an
2746 * extension of type "server_name" in the (extended) client hello.
2747 * The "extension_data" field of this extension SHALL contain
2748 * "ServerNameList" where:
2749 *
2750 * struct {
2751 * NameType name_type;
2752 * select(name_type) {
2753 * case host_name: HostName;
2754 * } name;
2755 * } ServerName;
2756 *
2757 * enum {
2758 * host_name(0), (255)
2759 * } NameType;
2760 *
2761 * opaque HostName<1..2^16-1>;
2762 *
2763 * struct {
2764 * ServerName server_name_list<1..2^16-1>
2765 * } ServerNameList;
2766 */
2767 var serverName = forge.util.createBuffer();
2768 serverName.putByte(0x00); // type host_name
2769 writeVector(serverName, 2, forge.util.createBuffer(c.virtualHost));
2770
2771 // ServerNameList is in extension_data
2772 var snList = forge.util.createBuffer();
2773 writeVector(snList, 2, serverName);
2774 writeVector(ext, 2, snList);
2775 extensions.putBuffer(ext);
2776 }
2777 var extLength = extensions.length();
2778 if(extLength > 0) {
2779 // add extension vector length
2780 extLength += 2;
2781 }
2782
2783 // determine length of the handshake message
2784 // cipher suites and compression methods size will need to be
2785 // updated if more get added to the list
2786 var sessionId = c.session.id;
2787 var length =
2788 sessionId.length + 1 + // session ID vector
2789 2 + // version (major + minor)
2790 4 + 28 + // random time and random bytes
2791 2 + cSuites + // cipher suites vector
2792 1 + cMethods + // compression methods vector
2793 extLength; // extensions vector
2794
2795 // build record fragment
2796 var rval = forge.util.createBuffer();
2797 rval.putByte(tls.HandshakeType.client_hello);
2798 rval.putInt24(length); // handshake length
2799 rval.putByte(c.version.major); // major version
2800 rval.putByte(c.version.minor); // minor version
2801 rval.putBytes(c.session.sp.client_random); // random time + bytes
2802 writeVector(rval, 1, forge.util.createBuffer(sessionId));
2803 writeVector(rval, 2, cipherSuites);
2804 writeVector(rval, 1, compressionMethods);
2805 if(extLength > 0) {
2806 writeVector(rval, 2, extensions);
2807 }
2808 return rval;
2809};
2810
2811/**
2812 * Creates a ServerHello message.
2813 *
2814 * @param c the connection.
2815 *
2816 * @return the ServerHello byte buffer.
2817 */
2818tls.createServerHello = function(c) {
2819 // determine length of the handshake message
2820 var sessionId = c.session.id;
2821 var length =
2822 sessionId.length + 1 + // session ID vector
2823 2 + // version (major + minor)
2824 4 + 28 + // random time and random bytes
2825 2 + // chosen cipher suite
2826 1; // chosen compression method
2827
2828 // build record fragment
2829 var rval = forge.util.createBuffer();
2830 rval.putByte(tls.HandshakeType.server_hello);
2831 rval.putInt24(length); // handshake length
2832 rval.putByte(c.version.major); // major version
2833 rval.putByte(c.version.minor); // minor version
2834 rval.putBytes(c.session.sp.server_random); // random time + bytes
2835 writeVector(rval, 1, forge.util.createBuffer(sessionId));
2836 rval.putByte(c.session.cipherSuite.id[0]);
2837 rval.putByte(c.session.cipherSuite.id[1]);
2838 rval.putByte(c.session.compressionMethod);
2839 return rval;
2840};
2841
2842/**
2843 * Creates a Certificate message.
2844 *
2845 * When this message will be sent:
2846 * This is the first message the client can send after receiving a server
2847 * hello done message and the first message the server can send after
2848 * sending a ServerHello. This client message is only sent if the server
2849 * requests a certificate. If no suitable certificate is available, the
2850 * client should send a certificate message containing no certificates. If
2851 * client authentication is required by the server for the handshake to
2852 * continue, it may respond with a fatal handshake failure alert.
2853 *
2854 * opaque ASN.1Cert<1..2^24-1>;
2855 *
2856 * struct {
2857 * ASN.1Cert certificate_list<0..2^24-1>;
2858 * } Certificate;
2859 *
2860 * @param c the connection.
2861 *
2862 * @return the Certificate byte buffer.
2863 */
2864tls.createCertificate = function(c) {
2865 // TODO: check certificate request to ensure types are supported
2866
2867 // get a certificate (a certificate as a PEM string)
2868 var client = (c.entity === tls.ConnectionEnd.client);
2869 var cert = null;
2870 if(c.getCertificate) {
2871 var hint;
2872 if(client) {
2873 hint = c.session.certificateRequest;
2874 } else {
2875 hint = c.session.extensions.server_name.serverNameList;
2876 }
2877 cert = c.getCertificate(c, hint);
2878 }
2879
2880 // buffer to hold certificate list
2881 var certList = forge.util.createBuffer();
2882 if(cert !== null) {
2883 try {
2884 // normalize cert to a chain of certificates
2885 if(!forge.util.isArray(cert)) {
2886 cert = [cert];
2887 }
2888 var asn1 = null;
2889 for(var i = 0; i < cert.length; ++i) {
2890 var msg = forge.pem.decode(cert[i])[0];
2891 if(msg.type !== 'CERTIFICATE' &&
2892 msg.type !== 'X509 CERTIFICATE' &&
2893 msg.type !== 'TRUSTED CERTIFICATE') {
2894 var error = new Error('Could not convert certificate from PEM; PEM ' +
2895 'header type is not "CERTIFICATE", "X509 CERTIFICATE", or ' +
2896 '"TRUSTED CERTIFICATE".');
2897 error.headerType = msg.type;
2898 throw error;
2899 }
2900 if(msg.procType && msg.procType.type === 'ENCRYPTED') {
2901 throw new Error('Could not convert certificate from PEM; PEM is encrypted.');
2902 }
2903
2904 var der = forge.util.createBuffer(msg.body);
2905 if(asn1 === null) {
2906 asn1 = forge.asn1.fromDer(der.bytes(), false);
2907 }
2908
2909 // certificate entry is itself a vector with 3 length bytes
2910 var certBuffer = forge.util.createBuffer();
2911 writeVector(certBuffer, 3, der);
2912
2913 // add cert vector to cert list vector
2914 certList.putBuffer(certBuffer);
2915 }
2916
2917 // save certificate
2918 cert = forge.pki.certificateFromAsn1(asn1);
2919 if(client) {
2920 c.session.clientCertificate = cert;
2921 } else {
2922 c.session.serverCertificate = cert;
2923 }
2924 } catch(ex) {
2925 return c.error(c, {
2926 message: 'Could not send certificate list.',
2927 cause: ex,
2928 send: true,
2929 alert: {
2930 level: tls.Alert.Level.fatal,
2931 description: tls.Alert.Description.bad_certificate
2932 }
2933 });
2934 }
2935 }
2936
2937 // determine length of the handshake message
2938 var length = 3 + certList.length(); // cert list vector
2939
2940 // build record fragment
2941 var rval = forge.util.createBuffer();
2942 rval.putByte(tls.HandshakeType.certificate);
2943 rval.putInt24(length);
2944 writeVector(rval, 3, certList);
2945 return rval;
2946};
2947
2948/**
2949 * Creates a ClientKeyExchange message.
2950 *
2951 * When this message will be sent:
2952 * This message is always sent by the client. It will immediately follow the
2953 * client certificate message, if it is sent. Otherwise it will be the first
2954 * message sent by the client after it receives the server hello done
2955 * message.
2956 *
2957 * Meaning of this message:
2958 * With this message, the premaster secret is set, either though direct
2959 * transmission of the RSA-encrypted secret, or by the transmission of
2960 * Diffie-Hellman parameters which will allow each side to agree upon the
2961 * same premaster secret. When the key exchange method is DH_RSA or DH_DSS,
2962 * client certification has been requested, and the client was able to
2963 * respond with a certificate which contained a Diffie-Hellman public key
2964 * whose parameters (group and generator) matched those specified by the
2965 * server in its certificate, this message will not contain any data.
2966 *
2967 * Meaning of this message:
2968 * If RSA is being used for key agreement and authentication, the client
2969 * generates a 48-byte premaster secret, encrypts it using the public key
2970 * from the server's certificate or the temporary RSA key provided in a
2971 * server key exchange message, and sends the result in an encrypted
2972 * premaster secret message. This structure is a variant of the client
2973 * key exchange message, not a message in itself.
2974 *
2975 * struct {
2976 * select(KeyExchangeAlgorithm) {
2977 * case rsa: EncryptedPreMasterSecret;
2978 * case diffie_hellman: ClientDiffieHellmanPublic;
2979 * } exchange_keys;
2980 * } ClientKeyExchange;
2981 *
2982 * struct {
2983 * ProtocolVersion client_version;
2984 * opaque random[46];
2985 * } PreMasterSecret;
2986 *
2987 * struct {
2988 * public-key-encrypted PreMasterSecret pre_master_secret;
2989 * } EncryptedPreMasterSecret;
2990 *
2991 * A public-key-encrypted element is encoded as a vector <0..2^16-1>.
2992 *
2993 * @param c the connection.
2994 *
2995 * @return the ClientKeyExchange byte buffer.
2996 */
2997tls.createClientKeyExchange = function(c) {
2998 // create buffer to encrypt
2999 var b = forge.util.createBuffer();
3000
3001 // add highest client-supported protocol to help server avoid version
3002 // rollback attacks
3003 b.putByte(c.session.clientHelloVersion.major);
3004 b.putByte(c.session.clientHelloVersion.minor);
3005
3006 // generate and add 46 random bytes
3007 b.putBytes(forge.random.getBytes(46));
3008
3009 // save pre-master secret
3010 var sp = c.session.sp;
3011 sp.pre_master_secret = b.getBytes();
3012
3013 // RSA-encrypt the pre-master secret
3014 var key = c.session.serverCertificate.publicKey;
3015 b = key.encrypt(sp.pre_master_secret);
3016
3017 /* Note: The encrypted pre-master secret will be stored in a
3018 public-key-encrypted opaque vector that has the length prefixed using
3019 2 bytes, so include those 2 bytes in the handshake message length. This
3020 is done as a minor optimization instead of calling writeVector(). */
3021
3022 // determine length of the handshake message
3023 var length = b.length + 2;
3024
3025 // build record fragment
3026 var rval = forge.util.createBuffer();
3027 rval.putByte(tls.HandshakeType.client_key_exchange);
3028 rval.putInt24(length);
3029 // add vector length bytes
3030 rval.putInt16(b.length);
3031 rval.putBytes(b);
3032 return rval;
3033};
3034
3035/**
3036 * Creates a ServerKeyExchange message.
3037 *
3038 * @param c the connection.
3039 *
3040 * @return the ServerKeyExchange byte buffer.
3041 */
3042tls.createServerKeyExchange = function(c) {
3043 // this implementation only supports RSA, no Diffie-Hellman support,
3044 // so this record is empty
3045
3046 // determine length of the handshake message
3047 var length = 0;
3048
3049 // build record fragment
3050 var rval = forge.util.createBuffer();
3051 if(length > 0) {
3052 rval.putByte(tls.HandshakeType.server_key_exchange);
3053 rval.putInt24(length);
3054 }
3055 return rval;
3056};
3057
3058/**
3059 * Gets the signed data used to verify a client-side certificate. See
3060 * tls.createCertificateVerify() for details.
3061 *
3062 * @param c the connection.
3063 * @param callback the callback to call once the signed data is ready.
3064 */
3065tls.getClientSignature = function(c, callback) {
3066 // generate data to RSA encrypt
3067 var b = forge.util.createBuffer();
3068 b.putBuffer(c.session.md5.digest());
3069 b.putBuffer(c.session.sha1.digest());
3070 b = b.getBytes();
3071
3072 // create default signing function as necessary
3073 c.getSignature = c.getSignature || function(c, b, callback) {
3074 // do rsa encryption, call callback
3075 var privateKey = null;
3076 if(c.getPrivateKey) {
3077 try {
3078 privateKey = c.getPrivateKey(c, c.session.clientCertificate);
3079 privateKey = forge.pki.privateKeyFromPem(privateKey);
3080 } catch(ex) {
3081 c.error(c, {
3082 message: 'Could not get private key.',
3083 cause: ex,
3084 send: true,
3085 alert: {
3086 level: tls.Alert.Level.fatal,
3087 description: tls.Alert.Description.internal_error
3088 }
3089 });
3090 }
3091 }
3092 if(privateKey === null) {
3093 c.error(c, {
3094 message: 'No private key set.',
3095 send: true,
3096 alert: {
3097 level: tls.Alert.Level.fatal,
3098 description: tls.Alert.Description.internal_error
3099 }
3100 });
3101 } else {
3102 b = privateKey.sign(b, null);
3103 }
3104 callback(c, b);
3105 };
3106
3107 // get client signature
3108 c.getSignature(c, b, callback);
3109};
3110
3111/**
3112 * Creates a CertificateVerify message.
3113 *
3114 * Meaning of this message:
3115 * This structure conveys the client's Diffie-Hellman public value
3116 * (Yc) if it was not already included in the client's certificate.
3117 * The encoding used for Yc is determined by the enumerated
3118 * PublicValueEncoding. This structure is a variant of the client
3119 * key exchange message, not a message in itself.
3120 *
3121 * When this message will be sent:
3122 * This message is used to provide explicit verification of a client
3123 * certificate. This message is only sent following a client
3124 * certificate that has signing capability (i.e. all certificates
3125 * except those containing fixed Diffie-Hellman parameters). When
3126 * sent, it will immediately follow the client key exchange message.
3127 *
3128 * struct {
3129 * Signature signature;
3130 * } CertificateVerify;
3131 *
3132 * CertificateVerify.signature.md5_hash
3133 * MD5(handshake_messages);
3134 *
3135 * Certificate.signature.sha_hash
3136 * SHA(handshake_messages);
3137 *
3138 * Here handshake_messages refers to all handshake messages sent or
3139 * received starting at client hello up to but not including this
3140 * message, including the type and length fields of the handshake
3141 * messages.
3142 *
3143 * select(SignatureAlgorithm) {
3144 * case anonymous: struct { };
3145 * case rsa:
3146 * digitally-signed struct {
3147 * opaque md5_hash[16];
3148 * opaque sha_hash[20];
3149 * };
3150 * case dsa:
3151 * digitally-signed struct {
3152 * opaque sha_hash[20];
3153 * };
3154 * } Signature;
3155 *
3156 * In digital signing, one-way hash functions are used as input for a
3157 * signing algorithm. A digitally-signed element is encoded as an opaque
3158 * vector <0..2^16-1>, where the length is specified by the signing
3159 * algorithm and key.
3160 *
3161 * In RSA signing, a 36-byte structure of two hashes (one SHA and one
3162 * MD5) is signed (encrypted with the private key). It is encoded with
3163 * PKCS #1 block type 0 or type 1 as described in [PKCS1].
3164 *
3165 * In DSS, the 20 bytes of the SHA hash are run directly through the
3166 * Digital Signing Algorithm with no additional hashing.
3167 *
3168 * @param c the connection.
3169 * @param signature the signature to include in the message.
3170 *
3171 * @return the CertificateVerify byte buffer.
3172 */
3173tls.createCertificateVerify = function(c, signature) {
3174 /* Note: The signature will be stored in a "digitally-signed" opaque
3175 vector that has the length prefixed using 2 bytes, so include those
3176 2 bytes in the handshake message length. This is done as a minor
3177 optimization instead of calling writeVector(). */
3178
3179 // determine length of the handshake message
3180 var length = signature.length + 2;
3181
3182 // build record fragment
3183 var rval = forge.util.createBuffer();
3184 rval.putByte(tls.HandshakeType.certificate_verify);
3185 rval.putInt24(length);
3186 // add vector length bytes
3187 rval.putInt16(signature.length);
3188 rval.putBytes(signature);
3189 return rval;
3190};
3191
3192/**
3193 * Creates a CertificateRequest message.
3194 *
3195 * @param c the connection.
3196 *
3197 * @return the CertificateRequest byte buffer.
3198 */
3199tls.createCertificateRequest = function(c) {
3200 // TODO: support other certificate types
3201 var certTypes = forge.util.createBuffer();
3202
3203 // common RSA certificate type
3204 certTypes.putByte(0x01);
3205
3206 // add distinguished names from CA store
3207 var cAs = forge.util.createBuffer();
3208 for(var key in c.caStore.certs) {
3209 var cert = c.caStore.certs[key];
3210 var dn = forge.pki.distinguishedNameToAsn1(cert.subject);
3211 var byteBuffer = forge.asn1.toDer(dn);
3212 cAs.putInt16(byteBuffer.length());
3213 cAs.putBuffer(byteBuffer);
3214 }
3215
3216 // TODO: TLS 1.2+ has a different format
3217
3218 // determine length of the handshake message
3219 var length =
3220 1 + certTypes.length() +
3221 2 + cAs.length();
3222
3223 // build record fragment
3224 var rval = forge.util.createBuffer();
3225 rval.putByte(tls.HandshakeType.certificate_request);
3226 rval.putInt24(length);
3227 writeVector(rval, 1, certTypes);
3228 writeVector(rval, 2, cAs);
3229 return rval;
3230};
3231
3232/**
3233 * Creates a ServerHelloDone message.
3234 *
3235 * @param c the connection.
3236 *
3237 * @return the ServerHelloDone byte buffer.
3238 */
3239tls.createServerHelloDone = function(c) {
3240 // build record fragment
3241 var rval = forge.util.createBuffer();
3242 rval.putByte(tls.HandshakeType.server_hello_done);
3243 rval.putInt24(0);
3244 return rval;
3245};
3246
3247/**
3248 * Creates a ChangeCipherSpec message.
3249 *
3250 * The change cipher spec protocol exists to signal transitions in
3251 * ciphering strategies. The protocol consists of a single message,
3252 * which is encrypted and compressed under the current (not the pending)
3253 * connection state. The message consists of a single byte of value 1.
3254 *
3255 * struct {
3256 * enum { change_cipher_spec(1), (255) } type;
3257 * } ChangeCipherSpec;
3258 *
3259 * @return the ChangeCipherSpec byte buffer.
3260 */
3261tls.createChangeCipherSpec = function() {
3262 var rval = forge.util.createBuffer();
3263 rval.putByte(0x01);
3264 return rval;
3265};
3266
3267/**
3268 * Creates a Finished message.
3269 *
3270 * struct {
3271 * opaque verify_data[12];
3272 * } Finished;
3273 *
3274 * verify_data
3275 * PRF(master_secret, finished_label, MD5(handshake_messages) +
3276 * SHA-1(handshake_messages)) [0..11];
3277 *
3278 * finished_label
3279 * For Finished messages sent by the client, the string "client
3280 * finished". For Finished messages sent by the server, the
3281 * string "server finished".
3282 *
3283 * handshake_messages
3284 * All of the data from all handshake messages up to but not
3285 * including this message. This is only data visible at the
3286 * handshake layer and does not include record layer headers.
3287 * This is the concatenation of all the Handshake structures as
3288 * defined in 7.4 exchanged thus far.
3289 *
3290 * @param c the connection.
3291 *
3292 * @return the Finished byte buffer.
3293 */
3294tls.createFinished = function(c) {
3295 // generate verify_data
3296 var b = forge.util.createBuffer();
3297 b.putBuffer(c.session.md5.digest());
3298 b.putBuffer(c.session.sha1.digest());
3299
3300 // TODO: determine prf function and verify length for TLS 1.2
3301 var client = (c.entity === tls.ConnectionEnd.client);
3302 var sp = c.session.sp;
3303 var vdl = 12;
3304 var prf = prf_TLS1;
3305 var label = client ? 'client finished' : 'server finished';
3306 b = prf(sp.master_secret, label, b.getBytes(), vdl);
3307
3308 // build record fragment
3309 var rval = forge.util.createBuffer();
3310 rval.putByte(tls.HandshakeType.finished);
3311 rval.putInt24(b.length());
3312 rval.putBuffer(b);
3313 return rval;
3314};
3315
3316/**
3317 * Creates a HeartbeatMessage (See RFC 6520).
3318 *
3319 * struct {
3320 * HeartbeatMessageType type;
3321 * uint16 payload_length;
3322 * opaque payload[HeartbeatMessage.payload_length];
3323 * opaque padding[padding_length];
3324 * } HeartbeatMessage;
3325 *
3326 * The total length of a HeartbeatMessage MUST NOT exceed 2^14 or
3327 * max_fragment_length when negotiated as defined in [RFC6066].
3328 *
3329 * type: The message type, either heartbeat_request or heartbeat_response.
3330 *
3331 * payload_length: The length of the payload.
3332 *
3333 * payload: The payload consists of arbitrary content.
3334 *
3335 * padding: The padding is random content that MUST be ignored by the
3336 * receiver. The length of a HeartbeatMessage is TLSPlaintext.length
3337 * for TLS and DTLSPlaintext.length for DTLS. Furthermore, the
3338 * length of the type field is 1 byte, and the length of the
3339 * payload_length is 2. Therefore, the padding_length is
3340 * TLSPlaintext.length - payload_length - 3 for TLS and
3341 * DTLSPlaintext.length - payload_length - 3 for DTLS. The
3342 * padding_length MUST be at least 16.
3343 *
3344 * The sender of a HeartbeatMessage MUST use a random padding of at
3345 * least 16 bytes. The padding of a received HeartbeatMessage message
3346 * MUST be ignored.
3347 *
3348 * If the payload_length of a received HeartbeatMessage is too large,
3349 * the received HeartbeatMessage MUST be discarded silently.
3350 *
3351 * @param c the connection.
3352 * @param type the tls.HeartbeatMessageType.
3353 * @param payload the heartbeat data to send as the payload.
3354 * @param [payloadLength] the payload length to use, defaults to the
3355 * actual payload length.
3356 *
3357 * @return the HeartbeatRequest byte buffer.
3358 */
3359tls.createHeartbeat = function(type, payload, payloadLength) {
3360 if(typeof payloadLength === 'undefined') {
3361 payloadLength = payload.length;
3362 }
3363 // build record fragment
3364 var rval = forge.util.createBuffer();
3365 rval.putByte(type); // heartbeat message type
3366 rval.putInt16(payloadLength); // payload length
3367 rval.putBytes(payload); // payload
3368 // padding
3369 var plaintextLength = rval.length();
3370 var paddingLength = Math.max(16, plaintextLength - payloadLength - 3);
3371 rval.putBytes(forge.random.getBytes(paddingLength));
3372 return rval;
3373};
3374
3375/**
3376 * Fragments, compresses, encrypts, and queues a record for delivery.
3377 *
3378 * @param c the connection.
3379 * @param record the record to queue.
3380 */
3381tls.queue = function(c, record) {
3382 // error during record creation
3383 if(!record) {
3384 return;
3385 }
3386
3387 if(record.fragment.length() === 0) {
3388 if(record.type === tls.ContentType.handshake ||
3389 record.type === tls.ContentType.alert ||
3390 record.type === tls.ContentType.change_cipher_spec) {
3391 // Empty handshake, alert of change cipher spec messages are not allowed per the TLS specification and should not be sent.
3392 return;
3393 }
3394 }
3395
3396 // if the record is a handshake record, update handshake hashes
3397 if(record.type === tls.ContentType.handshake) {
3398 var bytes = record.fragment.bytes();
3399 c.session.md5.update(bytes);
3400 c.session.sha1.update(bytes);
3401 bytes = null;
3402 }
3403
3404 // handle record fragmentation
3405 var records;
3406 if(record.fragment.length() <= tls.MaxFragment) {
3407 records = [record];
3408 } else {
3409 // fragment data as long as it is too long
3410 records = [];
3411 var data = record.fragment.bytes();
3412 while(data.length > tls.MaxFragment) {
3413 records.push(tls.createRecord(c, {
3414 type: record.type,
3415 data: forge.util.createBuffer(data.slice(0, tls.MaxFragment))
3416 }));
3417 data = data.slice(tls.MaxFragment);
3418 }
3419 // add last record
3420 if(data.length > 0) {
3421 records.push(tls.createRecord(c, {
3422 type: record.type,
3423 data: forge.util.createBuffer(data)
3424 }));
3425 }
3426 }
3427
3428 // compress and encrypt all fragmented records
3429 for(var i = 0; i < records.length && !c.fail; ++i) {
3430 // update the record using current write state
3431 var rec = records[i];
3432 var s = c.state.current.write;
3433 if(s.update(c, rec)) {
3434 // store record
3435 c.records.push(rec);
3436 }
3437 }
3438};
3439
3440/**
3441 * Flushes all queued records to the output buffer and calls the
3442 * tlsDataReady() handler on the given connection.
3443 *
3444 * @param c the connection.
3445 *
3446 * @return true on success, false on failure.
3447 */
3448tls.flush = function(c) {
3449 for(var i = 0; i < c.records.length; ++i) {
3450 var record = c.records[i];
3451
3452 // add record header and fragment
3453 c.tlsData.putByte(record.type);
3454 c.tlsData.putByte(record.version.major);
3455 c.tlsData.putByte(record.version.minor);
3456 c.tlsData.putInt16(record.fragment.length());
3457 c.tlsData.putBuffer(c.records[i].fragment);
3458 }
3459 c.records = [];
3460 return c.tlsDataReady(c);
3461};
3462
3463/**
3464 * Maps a pki.certificateError to a tls.Alert.Description.
3465 *
3466 * @param error the error to map.
3467 *
3468 * @return the alert description.
3469 */
3470var _certErrorToAlertDesc = function(error) {
3471 switch(error) {
3472 case true:
3473 return true;
3474 case forge.pki.certificateError.bad_certificate:
3475 return tls.Alert.Description.bad_certificate;
3476 case forge.pki.certificateError.unsupported_certificate:
3477 return tls.Alert.Description.unsupported_certificate;
3478 case forge.pki.certificateError.certificate_revoked:
3479 return tls.Alert.Description.certificate_revoked;
3480 case forge.pki.certificateError.certificate_expired:
3481 return tls.Alert.Description.certificate_expired;
3482 case forge.pki.certificateError.certificate_unknown:
3483 return tls.Alert.Description.certificate_unknown;
3484 case forge.pki.certificateError.unknown_ca:
3485 return tls.Alert.Description.unknown_ca;
3486 default:
3487 return tls.Alert.Description.bad_certificate;
3488 }
3489};
3490
3491/**
3492 * Maps a tls.Alert.Description to a pki.certificateError.
3493 *
3494 * @param desc the alert description.
3495 *
3496 * @return the certificate error.
3497 */
3498var _alertDescToCertError = function(desc) {
3499 switch(desc) {
3500 case true:
3501 return true;
3502 case tls.Alert.Description.bad_certificate:
3503 return forge.pki.certificateError.bad_certificate;
3504 case tls.Alert.Description.unsupported_certificate:
3505 return forge.pki.certificateError.unsupported_certificate;
3506 case tls.Alert.Description.certificate_revoked:
3507 return forge.pki.certificateError.certificate_revoked;
3508 case tls.Alert.Description.certificate_expired:
3509 return forge.pki.certificateError.certificate_expired;
3510 case tls.Alert.Description.certificate_unknown:
3511 return forge.pki.certificateError.certificate_unknown;
3512 case tls.Alert.Description.unknown_ca:
3513 return forge.pki.certificateError.unknown_ca;
3514 default:
3515 return forge.pki.certificateError.bad_certificate;
3516 }
3517};
3518
3519/**
3520 * Verifies a certificate chain against the given connection's
3521 * Certificate Authority store.
3522 *
3523 * @param c the TLS connection.
3524 * @param chain the certificate chain to verify, with the root or highest
3525 * authority at the end.
3526 *
3527 * @return true if successful, false if not.
3528 */
3529tls.verifyCertificateChain = function(c, chain) {
3530 try {
3531 // Make a copy of c.verifyOptions so that we can modify options.verify
3532 // without modifying c.verifyOptions.
3533 var options = {};
3534 for (var key in c.verifyOptions) {
3535 options[key] = c.verifyOptions[key];
3536 }
3537
3538 options.verify = function(vfd, depth, chain) {
3539 // convert pki.certificateError to tls alert description
3540 var desc = _certErrorToAlertDesc(vfd);
3541
3542 // call application callback
3543 var ret = c.verify(c, vfd, depth, chain);
3544 if(ret !== true) {
3545 if(typeof ret === 'object' && !forge.util.isArray(ret)) {
3546 // throw custom error
3547 var error = new Error('The application rejected the certificate.');
3548 error.send = true;
3549 error.alert = {
3550 level: tls.Alert.Level.fatal,
3551 description: tls.Alert.Description.bad_certificate
3552 };
3553 if(ret.message) {
3554 error.message = ret.message;
3555 }
3556 if(ret.alert) {
3557 error.alert.description = ret.alert;
3558 }
3559 throw error;
3560 }
3561
3562 // convert tls alert description to pki.certificateError
3563 if(ret !== vfd) {
3564 ret = _alertDescToCertError(ret);
3565 }
3566 }
3567
3568 return ret;
3569 };
3570
3571 // verify chain
3572 forge.pki.verifyCertificateChain(c.caStore, chain, options);
3573 } catch(ex) {
3574 // build tls error if not already customized
3575 var err = ex;
3576 if(typeof err !== 'object' || forge.util.isArray(err)) {
3577 err = {
3578 send: true,
3579 alert: {
3580 level: tls.Alert.Level.fatal,
3581 description: _certErrorToAlertDesc(ex)
3582 }
3583 };
3584 }
3585 if(!('send' in err)) {
3586 err.send = true;
3587 }
3588 if(!('alert' in err)) {
3589 err.alert = {
3590 level: tls.Alert.Level.fatal,
3591 description: _certErrorToAlertDesc(err.error)
3592 };
3593 }
3594
3595 // send error
3596 c.error(c, err);
3597 }
3598
3599 return !c.fail;
3600};
3601
3602/**
3603 * Creates a new TLS session cache.
3604 *
3605 * @param cache optional map of session ID to cached session.
3606 * @param capacity the maximum size for the cache (default: 100).
3607 *
3608 * @return the new TLS session cache.
3609 */
3610tls.createSessionCache = function(cache, capacity) {
3611 var rval = null;
3612
3613 // assume input is already a session cache object
3614 if(cache && cache.getSession && cache.setSession && cache.order) {
3615 rval = cache;
3616 } else {
3617 // create cache
3618 rval = {};
3619 rval.cache = cache || {};
3620 rval.capacity = Math.max(capacity || 100, 1);
3621 rval.order = [];
3622
3623 // store order for sessions, delete session overflow
3624 for(var key in cache) {
3625 if(rval.order.length <= capacity) {
3626 rval.order.push(key);
3627 } else {
3628 delete cache[key];
3629 }
3630 }
3631
3632 // get a session from a session ID (or get any session)
3633 rval.getSession = function(sessionId) {
3634 var session = null;
3635 var key = null;
3636
3637 // if session ID provided, use it
3638 if(sessionId) {
3639 key = forge.util.bytesToHex(sessionId);
3640 } else if(rval.order.length > 0) {
3641 // get first session from cache
3642 key = rval.order[0];
3643 }
3644
3645 if(key !== null && key in rval.cache) {
3646 // get cached session and remove from cache
3647 session = rval.cache[key];
3648 delete rval.cache[key];
3649 for(var i in rval.order) {
3650 if(rval.order[i] === key) {
3651 rval.order.splice(i, 1);
3652 break;
3653 }
3654 }
3655 }
3656
3657 return session;
3658 };
3659
3660 // set a session in the cache
3661 rval.setSession = function(sessionId, session) {
3662 // remove session from cache if at capacity
3663 if(rval.order.length === rval.capacity) {
3664 var key = rval.order.shift();
3665 delete rval.cache[key];
3666 }
3667 // add session to cache
3668 var key = forge.util.bytesToHex(sessionId);
3669 rval.order.push(key);
3670 rval.cache[key] = session;
3671 };
3672 }
3673
3674 return rval;
3675};
3676
3677/**
3678 * Creates a new TLS connection.
3679 *
3680 * See public createConnection() docs for more details.
3681 *
3682 * @param options the options for this connection.
3683 *
3684 * @return the new TLS connection.
3685 */
3686tls.createConnection = function(options) {
3687 var caStore = null;
3688 if(options.caStore) {
3689 // if CA store is an array, convert it to a CA store object
3690 if(forge.util.isArray(options.caStore)) {
3691 caStore = forge.pki.createCaStore(options.caStore);
3692 } else {
3693 caStore = options.caStore;
3694 }
3695 } else {
3696 // create empty CA store
3697 caStore = forge.pki.createCaStore();
3698 }
3699
3700 // setup default cipher suites
3701 var cipherSuites = options.cipherSuites || null;
3702 if(cipherSuites === null) {
3703 cipherSuites = [];
3704 for(var key in tls.CipherSuites) {
3705 cipherSuites.push(tls.CipherSuites[key]);
3706 }
3707 }
3708
3709 // set default entity
3710 var entity = (options.server || false) ?
3711 tls.ConnectionEnd.server : tls.ConnectionEnd.client;
3712
3713 // create session cache if requested
3714 var sessionCache = options.sessionCache ?
3715 tls.createSessionCache(options.sessionCache) : null;
3716
3717 // create TLS connection
3718 var c = {
3719 version: {major: tls.Version.major, minor: tls.Version.minor},
3720 entity: entity,
3721 sessionId: options.sessionId,
3722 caStore: caStore,
3723 sessionCache: sessionCache,
3724 cipherSuites: cipherSuites,
3725 connected: options.connected,
3726 virtualHost: options.virtualHost || null,
3727 verifyClient: options.verifyClient || false,
3728 verify: options.verify || function(cn, vfd, dpth, cts) {return vfd;},
3729 verifyOptions: options.verifyOptions || {},
3730 getCertificate: options.getCertificate || null,
3731 getPrivateKey: options.getPrivateKey || null,
3732 getSignature: options.getSignature || null,
3733 input: forge.util.createBuffer(),
3734 tlsData: forge.util.createBuffer(),
3735 data: forge.util.createBuffer(),
3736 tlsDataReady: options.tlsDataReady,
3737 dataReady: options.dataReady,
3738 heartbeatReceived: options.heartbeatReceived,
3739 closed: options.closed,
3740 error: function(c, ex) {
3741 // set origin if not set
3742 ex.origin = ex.origin ||
3743 ((c.entity === tls.ConnectionEnd.client) ? 'client' : 'server');
3744
3745 // send TLS alert
3746 if(ex.send) {
3747 tls.queue(c, tls.createAlert(c, ex.alert));
3748 tls.flush(c);
3749 }
3750
3751 // error is fatal by default
3752 var fatal = (ex.fatal !== false);
3753 if(fatal) {
3754 // set fail flag
3755 c.fail = true;
3756 }
3757
3758 // call error handler first
3759 options.error(c, ex);
3760
3761 if(fatal) {
3762 // fatal error, close connection, do not clear fail
3763 c.close(false);
3764 }
3765 },
3766 deflate: options.deflate || null,
3767 inflate: options.inflate || null
3768 };
3769
3770 /**
3771 * Resets a closed TLS connection for reuse. Called in c.close().
3772 *
3773 * @param clearFail true to clear the fail flag (default: true).
3774 */
3775 c.reset = function(clearFail) {
3776 c.version = {major: tls.Version.major, minor: tls.Version.minor};
3777 c.record = null;
3778 c.session = null;
3779 c.peerCertificate = null;
3780 c.state = {
3781 pending: null,
3782 current: null
3783 };
3784 c.expect = (c.entity === tls.ConnectionEnd.client) ? SHE : CHE;
3785 c.fragmented = null;
3786 c.records = [];
3787 c.open = false;
3788 c.handshakes = 0;
3789 c.handshaking = false;
3790 c.isConnected = false;
3791 c.fail = !(clearFail || typeof(clearFail) === 'undefined');
3792 c.input.clear();
3793 c.tlsData.clear();
3794 c.data.clear();
3795 c.state.current = tls.createConnectionState(c);
3796 };
3797
3798 // do initial reset of connection
3799 c.reset();
3800
3801 /**
3802 * Updates the current TLS engine state based on the given record.
3803 *
3804 * @param c the TLS connection.
3805 * @param record the TLS record to act on.
3806 */
3807 var _update = function(c, record) {
3808 // get record handler (align type in table by subtracting lowest)
3809 var aligned = record.type - tls.ContentType.change_cipher_spec;
3810 var handlers = ctTable[c.entity][c.expect];
3811 if(aligned in handlers) {
3812 handlers[aligned](c, record);
3813 } else {
3814 // unexpected record
3815 tls.handleUnexpected(c, record);
3816 }
3817 };
3818
3819 /**
3820 * Reads the record header and initializes the next record on the given
3821 * connection.
3822 *
3823 * @param c the TLS connection with the next record.
3824 *
3825 * @return 0 if the input data could be processed, otherwise the
3826 * number of bytes required for data to be processed.
3827 */
3828 var _readRecordHeader = function(c) {
3829 var rval = 0;
3830
3831 // get input buffer and its length
3832 var b = c.input;
3833 var len = b.length();
3834
3835 // need at least 5 bytes to initialize a record
3836 if(len < 5) {
3837 rval = 5 - len;
3838 } else {
3839 // enough bytes for header
3840 // initialize record
3841 c.record = {
3842 type: b.getByte(),
3843 version: {
3844 major: b.getByte(),
3845 minor: b.getByte()
3846 },
3847 length: b.getInt16(),
3848 fragment: forge.util.createBuffer(),
3849 ready: false
3850 };
3851
3852 // check record version
3853 var compatibleVersion = (c.record.version.major === c.version.major);
3854 if(compatibleVersion && c.session && c.session.version) {
3855 // session version already set, require same minor version
3856 compatibleVersion = (c.record.version.minor === c.version.minor);
3857 }
3858 if(!compatibleVersion) {
3859 c.error(c, {
3860 message: 'Incompatible TLS version.',
3861 send: true,
3862 alert: {
3863 level: tls.Alert.Level.fatal,
3864 description: tls.Alert.Description.protocol_version
3865 }
3866 });
3867 }
3868 }
3869
3870 return rval;
3871 };
3872
3873 /**
3874 * Reads the next record's contents and appends its message to any
3875 * previously fragmented message.
3876 *
3877 * @param c the TLS connection with the next record.
3878 *
3879 * @return 0 if the input data could be processed, otherwise the
3880 * number of bytes required for data to be processed.
3881 */
3882 var _readRecord = function(c) {
3883 var rval = 0;
3884
3885 // ensure there is enough input data to get the entire record
3886 var b = c.input;
3887 var len = b.length();
3888 if(len < c.record.length) {
3889 // not enough data yet, return how much is required
3890 rval = c.record.length - len;
3891 } else {
3892 // there is enough data to parse the pending record
3893 // fill record fragment and compact input buffer
3894 c.record.fragment.putBytes(b.getBytes(c.record.length));
3895 b.compact();
3896
3897 // update record using current read state
3898 var s = c.state.current.read;
3899 if(s.update(c, c.record)) {
3900 // see if there is a previously fragmented message that the
3901 // new record's message fragment should be appended to
3902 if(c.fragmented !== null) {
3903 // if the record type matches a previously fragmented
3904 // record, append the record fragment to it
3905 if(c.fragmented.type === c.record.type) {
3906 // concatenate record fragments
3907 c.fragmented.fragment.putBuffer(c.record.fragment);
3908 c.record = c.fragmented;
3909 } else {
3910 // error, invalid fragmented record
3911 c.error(c, {
3912 message: 'Invalid fragmented record.',
3913 send: true,
3914 alert: {
3915 level: tls.Alert.Level.fatal,
3916 description:
3917 tls.Alert.Description.unexpected_message
3918 }
3919 });
3920 }
3921 }
3922
3923 // record is now ready
3924 c.record.ready = true;
3925 }
3926 }
3927
3928 return rval;
3929 };
3930
3931 /**
3932 * Performs a handshake using the TLS Handshake Protocol, as a client.
3933 *
3934 * This method should only be called if the connection is in client mode.
3935 *
3936 * @param sessionId the session ID to use, null to start a new one.
3937 */
3938 c.handshake = function(sessionId) {
3939 // error to call this in non-client mode
3940 if(c.entity !== tls.ConnectionEnd.client) {
3941 // not fatal error
3942 c.error(c, {
3943 message: 'Cannot initiate handshake as a server.',
3944 fatal: false
3945 });
3946 } else if(c.handshaking) {
3947 // handshake is already in progress, fail but not fatal error
3948 c.error(c, {
3949 message: 'Handshake already in progress.',
3950 fatal: false
3951 });
3952 } else {
3953 // clear fail flag on reuse
3954 if(c.fail && !c.open && c.handshakes === 0) {
3955 c.fail = false;
3956 }
3957
3958 // now handshaking
3959 c.handshaking = true;
3960
3961 // default to blank (new session)
3962 sessionId = sessionId || '';
3963
3964 // if a session ID was specified, try to find it in the cache
3965 var session = null;
3966 if(sessionId.length > 0) {
3967 if(c.sessionCache) {
3968 session = c.sessionCache.getSession(sessionId);
3969 }
3970
3971 // matching session not found in cache, clear session ID
3972 if(session === null) {
3973 sessionId = '';
3974 }
3975 }
3976
3977 // no session given, grab a session from the cache, if available
3978 if(sessionId.length === 0 && c.sessionCache) {
3979 session = c.sessionCache.getSession();
3980 if(session !== null) {
3981 sessionId = session.id;
3982 }
3983 }
3984
3985 // set up session
3986 c.session = {
3987 id: sessionId,
3988 version: null,
3989 cipherSuite: null,
3990 compressionMethod: null,
3991 serverCertificate: null,
3992 certificateRequest: null,
3993 clientCertificate: null,
3994 sp: {},
3995 md5: forge.md.md5.create(),
3996 sha1: forge.md.sha1.create()
3997 };
3998
3999 // use existing session information
4000 if(session) {
4001 // only update version on connection, session version not yet set
4002 c.version = session.version;
4003 c.session.sp = session.sp;
4004 }
4005
4006 // generate new client random
4007 c.session.sp.client_random = tls.createRandom().getBytes();
4008
4009 // connection now open
4010 c.open = true;
4011
4012 // send hello
4013 tls.queue(c, tls.createRecord(c, {
4014 type: tls.ContentType.handshake,
4015 data: tls.createClientHello(c)
4016 }));
4017 tls.flush(c);
4018 }
4019 };
4020
4021 /**
4022 * Called when TLS protocol data has been received from somewhere and should
4023 * be processed by the TLS engine.
4024 *
4025 * @param data the TLS protocol data, as a string, to process.
4026 *
4027 * @return 0 if the data could be processed, otherwise the number of bytes
4028 * required for data to be processed.
4029 */
4030 c.process = function(data) {
4031 var rval = 0;
4032
4033 // buffer input data
4034 if(data) {
4035 c.input.putBytes(data);
4036 }
4037
4038 // process next record if no failure, process will be called after
4039 // each record is handled (since handling can be asynchronous)
4040 if(!c.fail) {
4041 // reset record if ready and now empty
4042 if(c.record !== null &&
4043 c.record.ready && c.record.fragment.isEmpty()) {
4044 c.record = null;
4045 }
4046
4047 // if there is no pending record, try to read record header
4048 if(c.record === null) {
4049 rval = _readRecordHeader(c);
4050 }
4051
4052 // read the next record (if record not yet ready)
4053 if(!c.fail && c.record !== null && !c.record.ready) {
4054 rval = _readRecord(c);
4055 }
4056
4057 // record ready to be handled, update engine state
4058 if(!c.fail && c.record !== null && c.record.ready) {
4059 _update(c, c.record);
4060 }
4061 }
4062
4063 return rval;
4064 };
4065
4066 /**
4067 * Requests that application data be packaged into a TLS record. The
4068 * tlsDataReady handler will be called when the TLS record(s) have been
4069 * prepared.
4070 *
4071 * @param data the application data, as a raw 'binary' encoded string, to
4072 * be sent; to send utf-16/utf-8 string data, use the return value
4073 * of util.encodeUtf8(str).
4074 *
4075 * @return true on success, false on failure.
4076 */
4077 c.prepare = function(data) {
4078 tls.queue(c, tls.createRecord(c, {
4079 type: tls.ContentType.application_data,
4080 data: forge.util.createBuffer(data)
4081 }));
4082 return tls.flush(c);
4083 };
4084
4085 /**
4086 * Requests that a heartbeat request be packaged into a TLS record for
4087 * transmission. The tlsDataReady handler will be called when TLS record(s)
4088 * have been prepared.
4089 *
4090 * When a heartbeat response has been received, the heartbeatReceived
4091 * handler will be called with the matching payload. This handler can
4092 * be used to clear a retransmission timer, etc.
4093 *
4094 * @param payload the heartbeat data to send as the payload in the message.
4095 * @param [payloadLength] the payload length to use, defaults to the
4096 * actual payload length.
4097 *
4098 * @return true on success, false on failure.
4099 */
4100 c.prepareHeartbeatRequest = function(payload, payloadLength) {
4101 if(payload instanceof forge.util.ByteBuffer) {
4102 payload = payload.bytes();
4103 }
4104 if(typeof payloadLength === 'undefined') {
4105 payloadLength = payload.length;
4106 }
4107 c.expectedHeartbeatPayload = payload;
4108 tls.queue(c, tls.createRecord(c, {
4109 type: tls.ContentType.heartbeat,
4110 data: tls.createHeartbeat(
4111 tls.HeartbeatMessageType.heartbeat_request, payload, payloadLength)
4112 }));
4113 return tls.flush(c);
4114 };
4115
4116 /**
4117 * Closes the connection (sends a close_notify alert).
4118 *
4119 * @param clearFail true to clear the fail flag (default: true).
4120 */
4121 c.close = function(clearFail) {
4122 // save session if connection didn't fail
4123 if(!c.fail && c.sessionCache && c.session) {
4124 // only need to preserve session ID, version, and security params
4125 var session = {
4126 id: c.session.id,
4127 version: c.session.version,
4128 sp: c.session.sp
4129 };
4130 session.sp.keys = null;
4131 c.sessionCache.setSession(session.id, session);
4132 }
4133
4134 if(c.open) {
4135 // connection no longer open, clear input
4136 c.open = false;
4137 c.input.clear();
4138
4139 // if connected or handshaking, send an alert
4140 if(c.isConnected || c.handshaking) {
4141 c.isConnected = c.handshaking = false;
4142
4143 // send close_notify alert
4144 tls.queue(c, tls.createAlert(c, {
4145 level: tls.Alert.Level.warning,
4146 description: tls.Alert.Description.close_notify
4147 }));
4148 tls.flush(c);
4149 }
4150
4151 // call handler
4152 c.closed(c);
4153 }
4154
4155 // reset TLS connection, do not clear fail flag
4156 c.reset(clearFail);
4157 };
4158
4159 return c;
4160};
4161
4162/* TLS API */
4163module.exports = forge.tls = forge.tls || {};
4164
4165// expose non-functions
4166for(var key in tls) {
4167 if(typeof tls[key] !== 'function') {
4168 forge.tls[key] = tls[key];
4169 }
4170}
4171
4172// expose prf_tls1 for testing
4173forge.tls.prf_tls1 = prf_TLS1;
4174
4175// expose sha1 hmac method
4176forge.tls.hmac_sha1 = hmac_sha1;
4177
4178// expose session cache creation
4179forge.tls.createSessionCache = tls.createSessionCache;
4180
4181/**
4182 * Creates a new TLS connection. This does not make any assumptions about the
4183 * transport layer that TLS is working on top of, ie: it does not assume there
4184 * is a TCP/IP connection or establish one. A TLS connection is totally
4185 * abstracted away from the layer is runs on top of, it merely establishes a
4186 * secure channel between a client" and a "server".
4187 *
4188 * A TLS connection contains 4 connection states: pending read and write, and
4189 * current read and write.
4190 *
4191 * At initialization, the current read and write states will be null. Only once
4192 * the security parameters have been set and the keys have been generated can
4193 * the pending states be converted into current states. Current states will be
4194 * updated for each record processed.
4195 *
4196 * A custom certificate verify callback may be provided to check information
4197 * like the common name on the server's certificate. It will be called for
4198 * every certificate in the chain. It has the following signature:
4199 *
4200 * variable func(c, certs, index, preVerify)
4201 * Where:
4202 * c The TLS connection
4203 * verified Set to true if certificate was verified, otherwise the alert
4204 * tls.Alert.Description for why the certificate failed.
4205 * depth The current index in the chain, where 0 is the server's cert.
4206 * certs The certificate chain, *NOTE* if the server was anonymous then
4207 * the chain will be empty.
4208 *
4209 * The function returns true on success and on failure either the appropriate
4210 * tls.Alert.Description or an object with 'alert' set to the appropriate
4211 * tls.Alert.Description and 'message' set to a custom error message. If true
4212 * is not returned then the connection will abort using, in order of
4213 * availability, first the returned alert description, second the preVerify
4214 * alert description, and lastly the default 'bad_certificate'.
4215 *
4216 * There are three callbacks that can be used to make use of client-side
4217 * certificates where each takes the TLS connection as the first parameter:
4218 *
4219 * getCertificate(conn, hint)
4220 * The second parameter is a hint as to which certificate should be
4221 * returned. If the connection entity is a client, then the hint will be
4222 * the CertificateRequest message from the server that is part of the
4223 * TLS protocol. If the connection entity is a server, then it will be
4224 * the servername list provided via an SNI extension the ClientHello, if
4225 * one was provided (empty array if not). The hint can be examined to
4226 * determine which certificate to use (advanced). Most implementations
4227 * will just return a certificate. The return value must be a
4228 * PEM-formatted certificate or an array of PEM-formatted certificates
4229 * that constitute a certificate chain, with the first in the array/chain
4230 * being the client's certificate.
4231 * getPrivateKey(conn, certificate)
4232 * The second parameter is an forge.pki X.509 certificate object that
4233 * is associated with the requested private key. The return value must
4234 * be a PEM-formatted private key.
4235 * getSignature(conn, bytes, callback)
4236 * This callback can be used instead of getPrivateKey if the private key
4237 * is not directly accessible in javascript or should not be. For
4238 * instance, a secure external web service could provide the signature
4239 * in exchange for appropriate credentials. The second parameter is a
4240 * string of bytes to be signed that are part of the TLS protocol. These
4241 * bytes are used to verify that the private key for the previously
4242 * provided client-side certificate is accessible to the client. The
4243 * callback is a function that takes 2 parameters, the TLS connection
4244 * and the RSA encrypted (signed) bytes as a string. This callback must
4245 * be called once the signature is ready.
4246 *
4247 * @param options the options for this connection:
4248 * server: true if the connection is server-side, false for client.
4249 * sessionId: a session ID to reuse, null for a new connection.
4250 * caStore: an array of certificates to trust.
4251 * sessionCache: a session cache to use.
4252 * cipherSuites: an optional array of cipher suites to use,
4253 * see tls.CipherSuites.
4254 * connected: function(conn) called when the first handshake completes.
4255 * virtualHost: the virtual server name to use in a TLS SNI extension.
4256 * verifyClient: true to require a client certificate in server mode,
4257 * 'optional' to request one, false not to (default: false).
4258 * verify: a handler used to custom verify certificates in the chain.
4259 * verifyOptions: an object with options for the certificate chain validation.
4260 * See documentation of pki.verifyCertificateChain for possible options.
4261 * verifyOptions.verify is ignored. If you wish to specify a verify handler
4262 * use the verify key.
4263 * getCertificate: an optional callback used to get a certificate or
4264 * a chain of certificates (as an array).
4265 * getPrivateKey: an optional callback used to get a private key.
4266 * getSignature: an optional callback used to get a signature.
4267 * tlsDataReady: function(conn) called when TLS protocol data has been
4268 * prepared and is ready to be used (typically sent over a socket
4269 * connection to its destination), read from conn.tlsData buffer.
4270 * dataReady: function(conn) called when application data has
4271 * been parsed from a TLS record and should be consumed by the
4272 * application, read from conn.data buffer.
4273 * closed: function(conn) called when the connection has been closed.
4274 * error: function(conn, error) called when there was an error.
4275 * deflate: function(inBytes) if provided, will deflate TLS records using
4276 * the deflate algorithm if the server supports it.
4277 * inflate: function(inBytes) if provided, will inflate TLS records using
4278 * the deflate algorithm if the server supports it.
4279 *
4280 * @return the new TLS connection.
4281 */
4282forge.tls.createConnection = tls.createConnection;
Note: See TracBrowser for help on using the repository browser.