tls: add `honorCipherOrder` option to tls.createServer()

Documented how to mitigate BEAST attacks.

doc/api/crypto.markdown

@@ -12,10 +12,12 @@ It also offers a set of wrappers for OpenSSL's hash, hmac, cipher, decipher, sig
 
 Creates a credentials object, with the optional details being a dictionary with keys:
 
-* `key` : a string holding the PEM encoded private key
+* `key` : A string holding the PEM encoded private key
-* `cert` : a string holding the PEM encoded certificate
+* `passphrase` : A string of passphrase for the private key
-* `ca` : either a string or list of strings of PEM encoded CA certificates to trust.
+* `cert` : A string holding the PEM encoded certificate
-* `ciphers`: a string describing the ciphers to use or exclude. Consult
+* `ca` : Either a string or list of strings of PEM encoded CA certificates to trust.
+* `crl` : Either a string or list of strings of PEM encoded CRLs (Certificate Revocation List)
+* `ciphers`: A string describing the ciphers to use or exclude. Consult
   <http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT> for details
   on the format.
 

doc/api/tls.markdown

@@ -82,9 +82,27 @@ The `options` object has these possibilities:
     omitted several well known "root" CAs will be used, like VeriSign.
     These are used to authorize connections.
 
+  - `crl` : Either a string or list of strings of PEM encoded CRLs (Certificate
+    Revocation List)
+
   - `ciphers`: A string describing the ciphers to use or exclude. Consult
     <http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT> for
     details on the format.
+    To mitigate [BEAST attacks]
+    (http://blog.ivanristic.com/2011/10/mitigating-the-beast-attack-on-tls.html),
+    it is recommended that you use this option in conjunction with the
+    `honorCipherOrder` option described below to prioritize the RC4 algorithm,
+    since it is a non-CBC cipher. A recommended cipher list follows:
+    `ECDHE-RSA-AES256-SHA384:AES256-SHA256:RC4-SHA:RC4:HIGH:!MD5:!aNULL:!EDH:!AESGCM`
+
+  - `honorCipherOrder` :
+	When choosing a cipher, use the server's preferences instead of the client
+	preferences.
+	Note that if SSLv2 is used, the server will send its list of preferences
+	to the client, and the client chooses the cipher.
+	Although, this option is disabled by default, it is *recommended* that you
+	use this option in conjunction with the `ciphers` option to mitigate
+	BEAST attacks.
 
   - `requestCert`: If `true` the server will request a certificate from
     clients that connect and attempt to verify that certificate. Default:

lib/tls.js

@@ -26,6 +26,7 @@ var events = require('events');
 var stream = require('stream');
 var END_OF_FILE = 42;
 var assert = require('assert').ok;
+var constants = require('constants');
 
 // Allow {CLIENT_RENEG_LIMIT} client-initiated session renegotiations
 // every {CLIENT_RENEG_WINDOW} seconds. An error event is emitted if more
@@ -1003,7 +1004,9 @@ Server.prototype.setOptions = function(options) {
   if (options.crl) this.crl = options.crl;
   if (options.ciphers) this.ciphers = options.ciphers;
   if (options.secureProtocol) this.secureProtocol = options.secureProtocol;
-  if (options.secureOptions) this.secureOptions = options.secureOptions;
+  var secureOptions = options.secureOptions || 0;
+  if (options.honorCipherOrder) secureOptions |= constants.SSL_OP_CIPHER_SERVER_PREFERENCE;
+  if (secureOptions) this.secureOptions = secureOptions;
   if (options.NPNProtocols) convertNPNProtocols(options.NPNProtocols, this);
   if (options.SNICallback) {
     this.SNICallback = options.SNICallback;