tls: Update cipher-list defaults, add command-line switches

doc/api/tls.markdown

@@ -25,8 +25,10 @@ To create a self-signed certificate with the CSR, do this:
 
 Alternatively you can send the CSR to a Certificate Authority for signing.
 
-(TODO: docs on creating a CA, for now interested users should just look at
-`test/fixtures/keys/Makefile` in the Node source code)
+For Perfect Forward Secrecy, it is required to generate Diffie-Hellman
+parameters:
+
+    openssl dhparam -outform PEM -out dhparam.pem 2048
 
 To create .pfx or .p12, do this:
 
@@ -134,6 +136,81 @@ the character "E" appended to the traditional abbreviations):
 Ephemeral methods may have some performance drawbacks, because key generation
 is expensive.
 
+## Modifying the Default Cipher Suite
+
+Node.js is built with a default suite of enabled and disabled ciphers.
+Currently, the default cipher suite is:
+
+    ECDHE-RSA-AES256-SHA384:DHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA256:
+    DHE-RSA-AES256-SHA256:ECDHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA256:
+    HIGH:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!SRP:!CAMELLIA
+
+This default can be overridden entirely using the `--cipher-list` command line
+switch or `NODE_CIPHER_LIST` environment variable. For instance:
+
+    node --cipher-list=ECDHE-RSA-AES256-SHA384:DHE-RSA-AES256-SHA384
+
+Setting the environment variable would have the same effect:
+
+    NODE_CIPHER_LIST=ECDHE-RSA-AES256-SHA384:DHE-RSA-AES256-SHA384
+
+CAUTION: The default cipher suite has been carefully selected to reflect current
+security best practices and risk mitigation. Changing the default cipher suite
+can have a significant impact on the security of an application. The
+`--cipher-list` and `NODE_CIPHER_LIST` options should only be used if
+absolutely necessary.
+
+### Using Legacy Default Cipher Suite ###
+
+It is possible for the built-in default cipher suite to change from one release
+of Node.js to another. For instance, v0.10.38 uses a different default than
+v0.12.2. Such changes can cause issues with applications written to assume
+certain specific defaults. To help buffer applications against such changes,
+the `--enable-legacy-cipher-list` command line switch or `NODE_LEGACY_CIPHER_LIST`
+environment variable can be set to specify a specific preset default:
+
+    # Use the v0.10.38 defaults
+    node --enable-legacy-cipher-list=v0.10.38
+    // or
+    NODE_LEGACY_CIPHER_LIST=v0.10.38
+
+    # Use the v0.12.2 defaults
+    node --enable-legacy-cipher-list=v0.12.2
+    // or
+    NODE_LEGACY_CIPHER_LIST=v0.12.2
+
+Currently, the values supported for the `enable-legacy-cipher-list` switch and
+`NODE_LEGACY_CIPHER_LIST` environment variable include:
+
+    v0.10.38 - To enable the default cipher suite used in v0.10.38
+
+      ECDHE-RSA-AES128-SHA256:AES128-GCM-SHA256:RC4:HIGH:!MD5:!aNULL:!EDH
+
+    v0.10.39 - To enable the default cipher suite used in v0.10.39
+
+      ECDHE-RSA-AES128-SHA256:AES128-GCM-SHA256:HIGH:!RC4:!MD5:!aNULL:!EDH
+
+    v0.12.2 - To enable the default cipher suite used in v0.12.2
+
+      ECDHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA256:AES128-GCM-SHA256:RC4:
+      HIGH:!MD5:!aNULL
+
+    v.0.12.3 - To enable the default cipher suite used in v0.12.3
+
+      ECDHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA256:AES128-GCM-SHA256:HIGH:
+      !RC4:!MD5:!aNULL
+
+These legacy cipher suites are also made available for use via the
+`getLegacyCiphers()` method:
+
+    var tls = require('tls');
+    console.log(tls.getLegacyCiphers('v0.10.38'));
+
+CAUTION: Changes to the default cipher suite are typically made in order to
+strengthen the default security for applications running within Node.js.
+Reverting back to the defaults used by older releases can weaken the security
+of your applications. The legacy cipher suites should only be used if absolutely
+necessary.
 
 ## tls.getCiphers()
 
@@ -144,6 +221,12 @@ Example:
     var ciphers = tls.getCiphers();
     console.log(ciphers); // ['AES128-SHA', 'AES256-SHA', ...]
 
+## tls.getLegacyCiphers(version)
+
+Returns the legacy default cipher suite for the specified Node.js release.
+
+Example:
+    var cipher_suite = tls.getLegacyCiphers('v0.10.38');
 
 ## tls.createServer(options[, secureConnectionListener])
 
@@ -170,31 +253,20 @@ automatically set as a listener for the [secureConnection][] event.  The
   - `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.
-
-    To mitigate [BEAST attacks] it is recommended that you use this option in
-    conjunction with the `honorCipherOrder` option described below to
-    prioritize the non-CBC cipher.
-
-    Defaults to
-    `ECDHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA256:AES128-GCM-SHA256:RC4:HIGH:!MD5:!aNULL`.
-    Consult the [OpenSSL cipher list format documentation] for details
-    on the format.
-
-    `ECDHE-RSA-AES128-SHA256`, `DHE-RSA-AES128-SHA256` and
-    `AES128-GCM-SHA256` are TLS v1.2 ciphers and used when node.js is
-    linked against OpenSSL 1.0.1 or newer, such as the bundled version
-    of OpenSSL.  Note that it is still possible for a TLS v1.2 client
-    to negotiate a weaker cipher unless `honorCipherOrder` is enabled.
+  - `ciphers`: A string describing the ciphers to use or exclude, separated by
+    `:`. The default cipher suite is:
 
-    `RC4` is used as a fallback for clients that speak on older version of
-    the TLS protocol.  `RC4` has in recent years come under suspicion and
-    should be considered compromised for anything that is truly sensitive.
-    It is speculated that state-level actors possess the ability to break it.
+        ECDHE-RSA-AES256-SHA384:DHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA256:
+        DHE-RSA-AES256-SHA256:ECDHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA256:
+        HIGH:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!SRP:!CAMELLIA
 
-    **NOTE**: Previous revisions of this section suggested `AES256-SHA` as an
-    acceptable cipher. Unfortunately, `AES256-SHA` is a CBC cipher and therefore
-    susceptible to [BEAST attacks]. Do *not* use it.
+    The default cipher suite prefers ECDHE and DHE ciphers for Perfect Forward
+    secrecy, while offering *some* backward compatibility. Old clients which
+    rely on insecure and deprecated RC4 or DES-based ciphers (like Internet
+    Explorer 6) aren't able to complete the handshake with the default
+    configuration. If you absolutely must support these clients, the
+    [TLS recommendations] may offer a compatible cipher suite. For more details
+    on the format, see the [OpenSSL cipher list format documentation].
 
   - `ecdhCurve`: A string describing a named curve to use for ECDH key agreement
     or false to disable ECDH.
@@ -212,7 +284,7 @@ automatically set as a listener for the [secureConnection][] event.  The
     times out.
 
   - `honorCipherOrder` : When choosing a cipher, use the server's preferences
-    instead of the client preferences.
+    instead of the client preferences. Default: `true`.
 
     Although, this option is disabled by default, it is *recommended* that you
     use this option in conjunction with the `ciphers` option to mitigate
@@ -853,5 +925,6 @@ The numeric representation of the local port.
 [ECDHE]: https://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman
 [asn1.js]: http://npmjs.org/package/asn1.js
 [OCSP request]: http://en.wikipedia.org/wiki/OCSP_stapling
+[TLS recommendations]: https://wiki.mozilla.org/Security/Server_Side_TLS
 [SSL_CTX_set_options]: https://www.openssl.org/docs/ssl/SSL_CTX_set_options.html
 [CVE-2014-3566]: https://access.redhat.com/articles/1232123

lib/_tls_wrap.js

@@ -735,10 +735,10 @@ Server.prototype.setOptions = function(options) {
     secureOptions |= constants.SSL_OP_CIPHER_SERVER_PREFERENCE;
   }
 
-  if (options.honorCipherOrder)
-    this.honorCipherOrder = true;
+  if (options.honorCipherOrder !== undefined)
+    this.honorCipherOrder = !!options.honorCipherOrder;
   else
-    this.honorCipherOrder = false;
+    this.honorCipherOrder = true;
 
   this.secureOptions = secureOptions;
 

lib/tls.js

@@ -21,6 +21,8 @@
 
 'use strict';
 
+var _crypto = process.binding('crypto');
+
 var net = require('net');
 var url = require('url');
 var util = require('util');
@@ -35,16 +37,14 @@ exports.CLIENT_RENEG_WINDOW = 600;
 
 exports.SLAB_BUFFER_SIZE = 10 * 1024 * 1024;
 
-exports.DEFAULT_CIPHERS =
-    // TLS 1.2
-    'ECDHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA256:AES128-GCM-SHA256:' +
-    // TLS 1.0
-    'RC4:HIGH:!MD5:!aNULL';
+exports.DEFAULT_CIPHERS = _crypto.DEFAULT_CIPHER_LIST;
 
 exports.DEFAULT_ECDH_CURVE = 'prime256v1';
 
+exports.getLegacyCiphers = _crypto.getLegacyCiphers;
+
 exports.getCiphers = function() {
-  var names = process.binding('crypto').getSSLCiphers();
+  var names = _crypto.getSSLCiphers();
   // Drop all-caps names in favor of their lowercase aliases,
   var ctx = {};
   names.forEach(function(name) {

src/node.cc

@@ -2929,6 +2929,9 @@ static void PrintHelp() {
 #endif
          "  --enable-ssl2        enable ssl2\n"
          "  --enable-ssl3        enable ssl3\n"
+         "  --cipher-list=val    specify the default TLS cipher list\n"
+         "  --enable-legacy-cipher-list=val \n"
+         "                       val = v0.10.38, v0.10.39, v0.12.2 or v0.12.3\n"
          "\n"
          "Environment variables:\n"
 #ifdef _WIN32
@@ -2946,6 +2949,9 @@ static void PrintHelp() {
          "                       (will extend linked-in data)\n"
 #endif
 #endif
+         "NODE_CIPHER_LIST       Override the default TLS cipher list\n"
+         "NODE_LEGACY_CIPHER_LIST=val\n"
+         "                       val = v0.10.38, v0.10.39, v0.12.2 or v0.12.3\n"
          "\n"
          "Documentation can be found at http://nodejs.org/\n");
 }
@@ -2985,6 +2991,7 @@ static void ParseArgs(int* argc,
   unsigned int new_argc = 1;
   new_v8_argv[0] = argv[0];
   new_argv[0] = argv[0];
+  bool using_legacy_cipher_list = false;
 
   unsigned int index = 1;
   while (index < nargs && argv[index][0] == '-') {
@@ -3040,6 +3047,20 @@ static void ParseArgs(int* argc,
     } else if (strcmp(arg, "--v8-options") == 0) {
       new_v8_argv[new_v8_argc] = "--help";
       new_v8_argc += 1;
+    } else if (strncmp(arg, "--cipher-list=", 14) == 0) {
+      if (!using_legacy_cipher_list) {
+        DEFAULT_CIPHER_LIST = arg + 14;
+      }
+    } else if (strncmp(arg, "--enable-legacy-cipher-list=", 28) == 0) {
+      // use the original v0.10.x/v0.12.x cipher lists
+      const char * legacy_list = legacy_cipher_list(arg+28);
+      if (legacy_list != NULL) {
+        using_legacy_cipher_list = true;
+        DEFAULT_CIPHER_LIST = legacy_list;
+      } else {
+        fprintf(stderr, "Error: An unknown legacy cipher list was specified\n");
+        exit(9);
+      }
 #if defined(NODE_HAVE_I18N_SUPPORT)
     } else if (strncmp(arg, "--icu-data-dir=", 15) == 0) {
       icu_data_dir = arg + 15;
@@ -3402,6 +3423,26 @@ void Init(int* argc,
     }
   }
 
+  const char * cipher_list = getenv("NODE_CIPHER_LIST");
+  if (cipher_list != NULL) {
+    DEFAULT_CIPHER_LIST = cipher_list;
+  }
+  // Allow the NODE_LEGACY_CIPHER_LIST envar to override the other
+  // cipher list options. NODE_LEGACY_CIPHER_LIST=v0.10.38 will use
+  // the cipher list from v0.10.38, NODE_LEGACY_CIPHER_LIST=v0.12.2 will
+  // use the cipher list from v0.12.2
+  const char * leg_cipher_id = getenv("NODE_LEGACY_CIPHER_LIST");
+  if (leg_cipher_id != NULL) {
+    const char * leg_cipher_list =
+      legacy_cipher_list(leg_cipher_id);
+    if (leg_cipher_list != NULL) {
+      DEFAULT_CIPHER_LIST = leg_cipher_list;
+    } else {
+      fprintf(stderr, "Error: An unknown legacy cipher list was specified\n");
+      exit(9);
+    }
+  }
+
 #if defined(NODE_HAVE_I18N_SUPPORT)
   if (icu_data_dir == NULL) {
     // if the parameter isn't given, use the env variable.

src/node.h

@@ -223,6 +223,17 @@ NODE_EXTERN void RunAtExit(Environment* env);
   }                                                                           \
   while (0)
 
+#define NODE_DEFINE_STRING_CONSTANT(isolate, target, constant)                \
+  do {                                                                        \
+    v8::Local<v8::String> constant_name =                                     \
+        v8::String::NewFromUtf8(isolate, #constant);                          \
+    v8::Local<v8::String> constant_value =                                    \
+        v8::String::NewFromUtf8(isolate, constant);                           \
+    v8::PropertyAttribute constant_attributes =                               \
+        static_cast<v8::PropertyAttribute>(v8::ReadOnly | v8::DontDelete);    \
+    (target)->ForceSet(constant_name, constant_value, constant_attributes);   \
+  } while (0)
+
 // Used to be a macro, hence the uppercase name.
 template <typename TypeName>
 inline void NODE_SET_METHOD(const TypeName& recv,

src/node_crypto.cc

@@ -77,6 +77,7 @@ namespace node {
 
 bool SSL2_ENABLE = false;
 bool SSL3_ENABLE = false;
+const char * DEFAULT_CIPHER_LIST = DEFAULT_CIPHER_LIST_HEAD;
 
 namespace crypto {
 
@@ -4851,6 +4852,26 @@ static void array_push_back(const TypeName* md,
   ctx->arr->Set(ctx->arr->Length(), OneByteString(ctx->env()->isolate(), from));
 }
 
+// borrowed from v8
+// (see http://v8.googlecode.com/svn/trunk/samples/shell.cc)
+const char* ToCString(const String::Utf8Value& value) {
+  return *value ? *value : "<string conversion failed>";
+}
+
+void DefaultCiphers(const v8::FunctionCallbackInfo<v8::Value>& args) {
+  Environment* env = Environment::GetCurrent(args.GetIsolate());
+  HandleScope scope(env->isolate());
+  v8::String::Utf8Value key(args[0]);
+  const char * list = legacy_cipher_list(ToCString(key));
+  if (list != NULL) {
+    args.GetReturnValue().Set(
+      v8::String::NewFromUtf8(args.GetIsolate(), list));
+  } else {
+    args.GetReturnValue().Set(
+      v8::String::NewFromUtf8(args.GetIsolate(),
+                             DEFAULT_CIPHER_LIST_HEAD));
+  }
+}
 
 void GetCiphers(const FunctionCallbackInfo<Value>& args) {
   Environment* env = Environment::GetCurrent(args.GetIsolate());
@@ -5171,6 +5192,9 @@ void InitCrypto(Handle<Object> target,
 
   NODE_DEFINE_CONSTANT(target, SSL3_ENABLE);
   NODE_DEFINE_CONSTANT(target, SSL2_ENABLE);
+
+  NODE_DEFINE_STRING_CONSTANT(env->isolate(), target, DEFAULT_CIPHER_LIST);
+  NODE_SET_METHOD(target, "getLegacyCiphers", DefaultCiphers);
 }
 
 }  // namespace crypto