Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

tls: The TLS API is inconsistent with the TCP API

Add 'secureConnect' event to tls.CleartextStream.

Fixes #1467.
  • Loading branch information...
commit 68cc173c6d2cde4f1869b24ec3bc690ef34da7ad 1 parent 0b92fa0
koichik authored
View
25 doc/api/tls.markdown
@@ -27,7 +27,7 @@ Alternatively you can send the CSR to a Certificate Authority for signing.
`test/fixtures/keys/Makefile` in the Node source code)
-### s = tls.connect(port, [host], [options], callback)
+### s = tls.connect(port, [host], [options], secureConnectListener)
Creates a new client connection to the given `port` and `host`. (If `host`
defaults to `localhost`.) `options` should be an object which specifies
@@ -49,14 +49,10 @@ defaults to `localhost`.) `options` should be an object which specifies
- `servername`: Servername for SNI (Server Name Indication) TLS extension.
-`tls.connect()` returns a [CleartextStream](#tls.CleartextStream) object.
+The `secureConnectListener` parameter will be added as a listener for the
+['secureConnect'](#event_secureConnect_) event.
-After the TLS/SSL handshake the `callback` is called. The `callback` will be
-called no matter if the server's certificate was authorized or not. It is up
-to the user to test `s.authorized` to see if the server certificate was signed
-by one of the specified CAs. If `s.authorized === false` then the error
-can be found in `s.authorizationError`. Also if NPN was used - you can check
-`s.npnProtocol` for negotiated protocol.
+`tls.connect()` returns a [CleartextStream](#tls.CleartextStream) object.
### STARTTLS
@@ -237,6 +233,18 @@ read/write an encrypted data as a cleartext data.
This instance implements a duplex [Stream](streams.html#streams) interfaces.
It has all the common stream methods and events.
+#### Event: 'secureConnect'
+
+`function () {}`
+
+This event is emitted after a new connection has been successfully handshaked.

s/successfully handshaked/established/ ?

@koichik Owner
koichik added a note

It is copied from server's 'secureConnection' event :-)
Just an image, I feel that "established" is a TCP level, "handshaked" is a SSL/TLS level.

Sure. It's not critical.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+The listener will be called no matter if the server's certificate was
+authorized or not. It is up to the user to test `cleartextStream.authorized`
+to see if the server certificate was signed by one of the specified CAs.
+If `cleartextStream.authorized === false` then the error can be found in
+`cleartextStream.authorizationError`. Also if NPN was used - you can check
+`cleartextStream.npnProtocol` for negotiated protocol.
+
#### cleartextStream.authorized
A boolean that is `true` if the peer certificate was signed by one of the
@@ -274,4 +282,3 @@ Example:
If the peer does not provide a certificate, it returns `null` or an empty
object.
-
View
5 lib/tls.js
@@ -981,6 +981,9 @@ exports.connect = function(port /* host, options, cb */) {
}
var cleartext = pipe(pair, socket);
+ if (cb) {
+ cleartext.on('secureConnect', cb);
+ }
socket.connect(port, host);
@@ -996,7 +999,7 @@ exports.connect = function(port /* host, options, cb */) {
cleartext.authorized = true;
}
- if (cb) cb();
+ cleartext.emit('secureConnect');
});
cleartext._controlReleased = true;
View
57 test/simple/test-tls-connect-simple.js
@@ -0,0 +1,57 @@
+// 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 fs = require('fs');
+
+var clientConnected = 0;
+var serverConnected = 0;
+
+var options = {
+ key: fs.readFileSync(common.fixturesDir + '/keys/agent1-key.pem'),
+ cert: fs.readFileSync(common.fixturesDir + '/keys/agent1-cert.pem')
+};
+
+var server = tls.Server(options, function(socket) {
+ if (++serverConnected === 2) {
+ server.close();
+ }
+});
+
+server.listen(common.PORT, function() {
+ var client1 = tls.connect(common.PORT, function() {
+ ++clientConnected;
+ client1.end();
+ });
+
+ var client2 = tls.connect(common.PORT);
+ client2.on('secureConnect', function() {
+ ++clientConnected;
+ client2.end();
+ });
+});
+
+process.on('exit', function() {
+ assert.equal(clientConnected, 2);
+ assert.equal(serverConnected, 2);
+});
@bnoordhuis

s/successfully handshaked/established/ ?

@koichik

It is copied from server's 'secureConnection' event :-)
Just an image, I feel that "established" is a TCP level, "handshaked" is a SSL/TLS level.

@bnoordhuis

Sure. It's not critical.

Please sign in to comment.
Something went wrong with that request. Please try again.