tls: Allow establishing secure connection on the existing socket

This is necessary to use SSL over HTTP tunnels.

Refs #2259, #2474.
Fixes #2489.

doc/api/tls.markdown

@@ -113,6 +113,10 @@ Creates a new client connection to the given `port` and `host` (old API) or
 
   - `port`: Port the client should connect to
 
+  - `socket`: Establish secure connection on a given socket rather than
+    creating a new socket. If this option is specified, `host` and `port`
+    are ignored.
+
   - `key`: A string or `Buffer` containing the private key of the client in
     PEM format.
 

lib/tls.js

@@ -1038,7 +1038,7 @@ exports.connect = function(/* [port, host], options, cb */) {
     cb = arguments[arguments.length - 1];
   }
 
-  var socket = new net.Stream();
+  var socket = options.socket ? options.socket : new net.Stream();
 
   var sslcontext = crypto.createCredentials(options);
 
@@ -1059,7 +1059,9 @@ exports.connect = function(/* [port, host], options, cb */) {
     cleartext.on('secureConnect', cb);
   }
 
-  socket.connect(options.port, options.host);
+  if (!options.socket) {
+    socket.connect(options.port, options.host);
+  }
 
   pair.on('secure', function() {
     var verifyError = pair.ssl.verifyError();

test/simple/test-tls-connect-given-socket.js

@@ -0,0 +1,59 @@
+// Copyright Joyent, Inc. and other Node contributors.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the
+// "Software"), to deal in the Software without restriction, including
+// without limitation the rights to use, copy, modify, merge, publish,
+// distribute, sublicense, and/or sell copies of the Software, and to permit
+// persons to whom the Software is furnished to do so, subject to the
+// following conditions:
+//
+// The above copyright notice and this permission notice shall be included
+// in all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+// USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+var common = require('../common');
+var assert = require('assert');
+var tls = require('tls');
+var net = require('net');
+var fs = require('fs');
+var path = require('path');
+
+var serverConnected = false;
+var clientConnected = false;
+
+var options = {
+  key: fs.readFileSync(path.join(common.fixturesDir, 'test_key.pem')),
+  cert: fs.readFileSync(path.join(common.fixturesDir, 'test_cert.pem'))
+};
+
+var server = tls.createServer(options, function(socket) {
+  serverConnected = true;
+  socket.end('Hello');
+}).listen(common.PORT, function() {
+  var socket = net.connect(common.PORT, function() {
+    var client = tls.connect({socket: socket}, function() {
+      clientConnected = true;
+      var data = '';
+      client.on('data', function(chunk) {
+        data += chunk.toString();
+      });
+      client.on('end', function() {
+        assert.equal(data, 'Hello');
+        server.close();
+      });
+    });
+  });
+});
+
+process.on('exit', function() {
+  assert(serverConnected);
+  assert(clientConnected);
+});