Improvements to tls API documentation, batch 1

doc/api/crypto.md

@@ -1082,26 +1082,15 @@ deprecated: v0.11.13
 
 > Stability: 0 - Deprecated: Use [`tls.createSecureContext()`][] instead.
 
-The `crypto.createCredentials()` method is a deprecated alias for creating
-and returning a `tls.SecureContext` object. The `crypto.createCredentials()`
-method should not be used.
+- `details` {Object} Identical to [`tls.createSecureContext()`][].
 
-The optional `details` argument is a hash object with keys:
+The `crypto.createCredentials()` method is a deprecated function for creating
+and returning a `tls.SecureContext`. It should not be used. Replace it with
+[`tls.createSecureContext()`][] which has the exact same arguments and return
+value.
 
-* `pfx` : {String|Buffer} - PFX or PKCS12 encoded private
-  key, certificate and CA certificates
-* `key` : {String} - PEM encoded private key
-* `passphrase` : {String} - passphrase for the private key or PFX
-* `cert` : {String} - PEM encoded certificate
-* `ca` : {String|Array} - Either a string or array of strings of PEM encoded CA
-  certificates to trust.
-* `crl` : {String|Array} - Either a string or array of strings of PEM encoded CRLs
-  (Certificate Revocation List)
-* `ciphers`: {String} using the [OpenSSL cipher list format][] describing the
-  cipher algorithms to use or exclude.
-
-If no 'ca' details are given, Node.js will use Mozilla's default
-[publicly trusted list of CAs][].
+Returns a `tls.SecureContext`, as-if [`tls.createSecureContext()`][] had been
+called.
 
 ### crypto.createDecipher(algorithm, password)
 <!-- YAML
@@ -1653,8 +1642,8 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL.
   </tr>
   <tr>
     <td><code>SSL_OP_CIPHER_SERVER_PREFERENCE</code></td>
-    <td>Uses the server's preferences instead of the clients when selecting a
-    cipher. See
+    <td>Attempts to use the server's preferences instead of the client's when
+    selecting a cipher. Behaviour depends on protocol version. See
     https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html.</td>
   </tr>
   <tr>
@@ -1682,7 +1671,7 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL.
   </tr>
   <tr>
     <td><code>SSL_OP_LEGACY_SERVER_CONNECT</code></td>
-    <td>Allow initial connection to servers that do not support RI.</td>
+    <td>Allows initial connection to servers that do not support RI.</td>
   </tr>
   <tr>
     <td><code>SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER</code></td>
@@ -1980,4 +1969,4 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL.
 [RFC 3526]: https://www.rfc-editor.org/rfc/rfc3526.txt
 [stream]: stream.html
 [stream-writable-write]: stream.html#stream_writable_write_chunk_encoding_callback
-[Crypto Constants]: #crypto_crypto_constants
+[Crypto Constants]: #crypto_crypto_constants_1

lib/_tls_common.js

@@ -12,9 +12,9 @@ var crypto = null;
 const binding = process.binding('crypto');
 const NativeSecureContext = binding.SecureContext;
 
-function SecureContext(secureProtocol, flags, context) {
+function SecureContext(secureProtocol, secureOptions, context) {
   if (!(this instanceof SecureContext)) {
-    return new SecureContext(secureProtocol, flags, context);
+    return new SecureContext(secureProtocol, secureOptions, context);
   }
 
   if (context) {
@@ -29,7 +29,7 @@ function SecureContext(secureProtocol, flags, context) {
     }
   }
 
-  if (flags) this.context.setOptions(flags);
+  if (secureOptions) this.context.setOptions(secureOptions);
 }
 
 exports.SecureContext = SecureContext;

lib/_tls_wrap.js

@@ -745,18 +745,19 @@ TLSSocket.prototype.getProtocol = function() {
 //   "PATH_LENGTH_EXCEEDED", "INVALID_PURPOSE" "CERT_UNTRUSTED",
 //   "CERT_REJECTED"
 //
-function Server(/* [options], listener */) {
-  var options, listener;
+function Server(options, listener) {
+  if (!(this instanceof Server))
+    return new Server(options, listener);
 
-  if (arguments[0] !== null && typeof arguments[0] === 'object') {
-    options = arguments[0];
-    listener = arguments[1];
-  } else if (typeof arguments[0] === 'function') {
+  if (typeof options === 'function') {
+    listener = options;
     options = {};
-    listener = arguments[0];
+  } else if (options == null || typeof options === 'object') {
+    options = options || {};
+  } else {
+    throw new TypeError('options must be an object');
   }
 
-  if (!(this instanceof Server)) return new Server(options, listener);
 
   this._contexts = [];
 
@@ -975,6 +976,11 @@ function normalizeConnectArgs(listArgs) {
   var options = args[0];
   var cb = args[1];
 
+  // If args[0] was options, then normalize dealt with it.
+  // If args[0] is port, or args[0], args[1]  is host,port, we need to
+  // find the options and merge them in, normalize's options has only
+  // the host/port/path args that it knows about, not the tls options.
+  // This means that options.host overrides a host arg.
   if (listArgs[1] !== null && typeof listArgs[1] === 'object') {
     options = util._extend(options, listArgs[1]);
   } else if (listArgs[2] !== null && typeof listArgs[2] === 'object') {
@@ -984,7 +990,7 @@ function normalizeConnectArgs(listArgs) {
   return (cb) ? [options, cb] : [options];
 }
 
-exports.connect = function(/* [port, host], options, cb */) {
+exports.connect = function(/* [port,] [host,] [options,] [cb] */) {
   const argsLen = arguments.length;
   var args = new Array(argsLen);
   for (var i = 0; i < argsLen; i++)

test/fixtures/raw-key.pem

@@ -0,0 +1,15 @@
+-----BEGIN RSA PRIVATE KEY-----
+MIICXAIBAAKBgQChmQeFwsaomtQbw9Nm55Dn6KSR9bkY8PDroQUeTNa90BlIbhGs
+KYm4l7bERaasFgOrkcQpk45fdDVYPjKxraZiGXXKjSIDYeDAIC/+CkwQKrejgCPm
+Js4gV4g+npvwi1gVr2NAg7fkJOyEW2TDp4dsAD8qtG8Aml0C1hJXwFYmBwIDAQAB
+AoGAVgZpAsQVjVwe3kj5GSbc9Rfbw/fTeXuKRWWKm/67soA9dVli/wt9zU62dPW/
+LIzrl0IZ8ygh+p6aZ0d1JTEUCPx7e0KocCmNg77i5AG0eK5i/KKjTWB4UGRDylfD
+dnBXQc814bK+VB0mrcp46U/7tLGYkV2Kz/LiNpmxKwITS4ECQQDPoA6WIU87Eulq
+OuVmJnFIQ2IR3SycVisO7TUq2MItq2U4BwsA3aQ4ehpP/uJdAfJEfwi2omRV5pGb
+806pWkfPAkEAxz+igHS8tR11aLck71dD4BRBY7XZCUg6G4zmYYWsqj0yvM6c4Yn0
+HRcrZqFvV/xuMFphWEmMBhrqLvgy66yUSQJBALkei4LeRid0sDswMhMHGaAFvG4T
+FtB5n8CaTPpb854GoKP42521ANP+QnGq36dvsdPStDEqz20rvA4hPLSQs08CQCV8
+eWxFikNg+XfsDQzilCiSZwMFcYHnjtckGSv75FJbFTKkhKuCMuVOOKIkeThKi8iZ
+GHttyuRTKAASPjJM09ECQBrhlKJwYKuUDMp3qkLBgrXYqbFxZtkS2GeFMUfLcRlx
+oMrTFEczz9lZ0huTuQYPeAAOY0Gd84mL0kQqTRTzNLs=
+-----END RSA PRIVATE KEY-----

test/parallel/test-tls-multi-key.js

@@ -11,8 +11,8 @@ var fs = require('fs');
 
 var options = {
   key: [
+    fs.readFileSync(common.fixturesDir + '/keys/ec-key.pem'),
     fs.readFileSync(common.fixturesDir + '/keys/agent1-key.pem'),
-    fs.readFileSync(common.fixturesDir + '/keys/ec-key.pem')
   ],
   cert: [
     fs.readFileSync(common.fixturesDir + '/keys/agent1-cert.pem'),

test/parallel/test-tls-no-cert-required.js

@@ -1,15 +1,30 @@
 'use strict';
-var common = require('../common');
+const assert = require('assert');
+const common = require('../common');
 
 if (!common.hasCrypto) {
   common.skip('missing crypto');
   return;
 }
-var tls = require('tls');
+const tls = require('tls');
 
 // Omitting the cert or pfx option to tls.createServer() should not throw.
 // AECDH-NULL-SHA is a no-authentication/no-encryption cipher and hence
 // doesn't need a certificate.
-tls.createServer({ ciphers: 'AECDH-NULL-SHA' }).listen(0, function() {
+tls.createServer({ ciphers: 'AECDH-NULL-SHA' })
+  .listen(0, common.mustCall(close));
+
+tls.createServer(assert.fail)
+  .listen(0, common.mustCall(close));
+
+tls.createServer({})
+  .listen(0, common.mustCall(close));
+
+assert.throws(() => tls.createServer('this is not valid'), TypeError);
+
+tls.createServer()
+  .listen(0, common.mustCall(close));
+
+function close() {
   this.close();
-});
+}