diff --git a/doc/api/tls.md b/doc/api/tls.md index 158d41a0a283de..471ce1410012fe 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -463,7 +463,11 @@ connection is open. added: v0.11.4 --> -* `socket` {net.Socket} An instance of [`net.Socket`][] +* `socket` {net.Socket} An instance of [`net.Socket`][]. Optional, by default + a new TCP or Pipe object will be created, unconnected (it is the caller's + responsibility to connect it). Its unusual to not provide a pre-existing + `socket` when directly creating a `tls.TLSSocket`. The auto-creation feature + is mostly intended for internal use. * `options` {Object} * `isServer`: The SSL/TLS protocol is asymetrical, TLSSockets must know if they are to behave as a server or a client. If `true` the TLS socket will be @@ -481,6 +485,8 @@ added: v0.11.4 * `requestOCSP` {boolean} If `true`, specifies that the OCSP status request extension will be added to the client hello and an `'OCSPResponse'` event will be emitted on the socket before establishing a secure communication + * `pipe`: Optional. When `socket` is not passed, a Pipe will be created if + true, and a TCP socket will be created otherwise. * `secureContext`: Optional TLS context object created with [`tls.createSecureContext()`][]. If a `secureContext` is _not_ provided, one will be created by passing the entire `options` object to @@ -490,7 +496,18 @@ added: v0.11.4 * ...: Optional [`tls.createSecureContext()`][] options can be provided, see the `secureContext` option for more information. -Construct a new `tls.TLSSocket` object from an existing TCP socket. +Directly construct a new `tls.TLSSocket` object on top of an underlying +socket. + +Always prefer calling [`tls.connect()`][] to direct construction, unless a +socket already exists, and a TLS connection is to be initiated on it. This +latter case is common when implementing protocols like SMTP, that can start off +insecure, and then initiate a secure channel over the existing TCP connection. + +***Warning***: When directly constructing a `tls.TLSSocket` instead of using +[`tls.connect()`][] it is the caller's responsibility to: +- manage the lifetime of the the underlying socket, including connecting it; +- validate the peer certificate and identity, see the [`'secure'`][] event. ### Event: 'OCSPResponse' The `'secureConnect'` event is emitted after the handshaking process for a new -connection has successfully completed. The listener callback will be called +connection has successfully completed. The event will be emitted regardless of whether or not the server's certificate has been authorized. It is the client's responsibility to check the `tlsSocket.authorized` property to determine if the server certificate was signed by one of the specified CAs. If @@ -521,6 +538,38 @@ determine if the server certificate was signed by one of the specified CAs. If the `tlsSocket.alpnProtocol` or `tlsSocket.npnProtocol` properties can be checked to determine the negotiated protocol. +***Note***: Only for sockets created using `tls.connect()`. + +### Event: 'secure' + + +Emitted after the handshake is complete. + +***Warning***: Before using the connection, the user *must* make the following +checks or the connection should be considered completely insecure: + +1. Verify that the peer certificate is valid, see [`ssl.verifyError()`][]. +2. Verify that the peer certificate is for the expected host, see + [`tls.checkServerIdentity()`][] and [`tls.TLSSocket.getPeerCertificate()`][]. + +Example: + +``` +tlsSocket.on('secure', function() { + const err = this.ssl.verifyError() || + tls.checkServerIdentity(hostname, this.getPeerCertificate()); + if (err) + this.emit('error', err); +}); +``` + +### Event: 'connect' + + ### tlsSocket.address() + +Returns an `Error` object if the peer's certificate fails validation. Validation +includes many checks, but including +that the certificate is either trusted or can be chained to a trusted +CA (see the `ca` option of [`tls.createSecureContext()`][] for more information). + +***Warning***: Validation explicitly does *not* include any authentication of +the identity. [`tls.checkServerIdentity()`][] can be used to authenticate the +identity of the peer. + + ## tls.connect(port[, host][, options][, callback]) + + * host: {String) The hostname that the `cert` should certify. + * cert: {Object} Object representing the peer's certificate. + +Check's that the certificate was issued for `host`. + +Returns `undefined` if `host` matches any of the certificate's names. If it does +not match, it returns an Error with the following additional properties: +- reason: {String} Describe why the certificate does not match the host. +- host: {String} The `host`. +- cert: {Object} The `cert`. + +Example: +``` +if(!tls.checkServerIdentity('example.com', tlsSock.getPeerCertificate()) + // Peer is not authentic, do not trust the peer is 'example.com'! +``` + ## tls.getCiphers()