【TLS/SSL】升级到 v6.10.0

tls/modifying_the_default_tls_cipher_suite.md

@@ -34,9 +34,29 @@ line switch. For instance, the following makes
 node --tls-cipher-list="ECDHE-RSA-AES128-GCM-SHA256:!RC4"
 ```
 
+The default can also be replaced on a per client or server basis using the
+`ciphers` option from [`tls.createSecureContext()`][], which is also available
+in [`tls.createServer()`], [`tls.connect()`], and when creating new
+[`tls.TLSSocket`]s.
+
+Consult [OpenSSL cipher list format documentation][] for details on the format.
+
 *Note*: The default cipher suite included within Node.js 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 `--tls-cipher-list` switch should by used only if
-absolutely necessary.
+of an application. The `--tls-cipher-list` switch and `ciphers` option should by
+used only if absolutely necessary.
+
+The default cipher suite prefers GCM ciphers for [Chrome's 'modern
+cryptography' setting] and also prefers ECDHE and DHE ciphers for Perfect
+Forward Secrecy, while offering *some* backward compatibility.
+
+128 bit AES is preferred over 192 and 256 bit AES in light of [specific
+attacks affecting larger AES key sizes].
+
+Old clients that rely on insecure and deprecated RC4 or DES-based ciphers
+(like Internet Explorer 6) cannot complete the handshaking process with
+the default configuration. If these clients _must_ be supported, the
+[TLS recommendations] may offer a compatible cipher suite. For more details
+on the format, see the [OpenSSL cipher list format documentation].
 

tls/new_tls_tlssocket_socket_options.md

@@ -4,12 +4,14 @@ added: v0.11.4
 
 * `socket` {net.Socket} An instance of [`net.Socket`][]
 * `options` {Object}
-  * `secureContext`: An optional TLS context object from
-     [`tls.createSecureContext()`][]
-  * `isServer`: If `true` the TLS socket will be instantiated in server-mode.
-    Defaults to `false`.
+  * `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
+    instantiated as a server.  Defaults to `false`.
   * `server` {net.Server} An optional [`net.Server`][] instance.
-  * `requestCert`: Optional, see [`tls.createServer()`][]
+  * `requestCert`: Whether to authenticate the remote peer by requesting a
+     certificate. Clients always request a server certificate. Servers
+     (`isServer` is true) may optionally set `requestCert` to true to request a
+     client certificate.
   * `rejectUnauthorized`: Optional, see [`tls.createServer()`][]
   * `NPNProtocols`: Optional, see [`tls.createServer()`][]
   * `ALPNProtocols`: Optional, see [`tls.createServer()`][]
@@ -18,6 +20,13 @@ 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
-
+  * `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
+    `tls.createSecureContext()`. *Note*: In effect, all
+    [`tls.createSecureContext()`][] options can be provided, but they will be
+    _completely ignored_ unless the `secureContext` option is missing.
+  * ...: 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.
 

tls/perfect_forward_secrecy.md

@@ -24,15 +24,16 @@ Ephemeral methods may have some performance drawbacks, because key generation
 is expensive.
 
 To use Perfect Forward Secrecy using `DHE` with the `tls` module, it is required
-to generate Diffie-Hellman parameters. The following illustrates the use of the
-OpenSSL command-line interface to generate such parameters:
+to generate Diffie-Hellman parameters and specify them with the `dhparam`
+option to [`tls.createSecureContext()`][]. The following illustrates the use of
+the OpenSSL command-line interface to generate such parameters:
 
 ```sh
 openssl dhparam -outform PEM -out dhparam.pem 2048
 ```
 
 If using Perfect Forward Secrecy using `ECDHE`, Diffie-Hellman parameters are
-not required and a default ECDHE curve will be used. The `ecdheCurve` property
-can be used when creating a TLS Server to specify the name of an
-alternative curve to use.
+not required and a default ECDHE curve will be used. The `ecdhCurve` property
+can be used when creating a TLS Server to specify the name of an alternative
+curve to use, see [`tls.createServer()`] for more info.
 

tls/tls_connect_options_callback.md

@@ -3,30 +3,17 @@ added: v0.11.3
 -->
 
 * `options` {Object}
-  * `host` {string} Host the client should connect to.
+  * `host` {string} Host the client should connect to, defaults to 'localhost'.
   * `port` {number} Port the client should connect to.
-  * `socket` {net.Socket} Establish secure connection on a given socket rather
-    than creating a new socket. If this option is specified, `host` and `port`
-    are ignored.
   * `path` {string} Creates unix socket connection to path. If this option is
     specified, `host` and `port` are ignored.
-  * `pfx` {string|Buffer} A string or `Buffer` containing the private key,
-    certificate, and CA certs of the client in PFX or PKCS12 format.
-  * `key` {string|string[]|Buffer|Buffer[]} A string, `Buffer`, array of
-    strings, or array of `Buffer`s containing the private key of the client in
-    PEM format.
-  * `passphrase` {string} A string containing the passphrase for the private key
-    or pfx.
-  * `cert` {string|string[]|Buffer|Buffer[]} A string, `Buffer`, array of
-    strings, or array of `Buffer`s containing the certificate key of the client
-    in PEM format.
-  * `ca` {string|string[]|Buffer|Buffer[]} A string, `Buffer`, array of strings,
-    or array of `Buffer`s of trusted certificates in PEM format. If this is
-    omitted several well known "root" CAs (like VeriSign) will be used. These
-    are used to authorize connections.
-  * `ciphers` {string} A string describing the ciphers to use or exclude,
-    separated by `:`. Uses the same default cipher suite as
-    [`tls.createServer()`][].
+  * `socket` {net.Socket} Establish secure connection on a given socket rather
+    than creating a new socket. If this option is specified, `path`, `host` and
+    `port` are ignored.  Usually, a socket is already connected when passed to
+    `tls.connect()`, but it can be connected later. Note that
+    connection/disconnection/destruction of `socket` is the user's
+    responsibility, calling `tls.connect()` will not cause `net.connect()` to be
+    called.
   * `rejectUnauthorized` {boolean} If `true`, the server certificate is verified
     against the list of supplied CAs. An `'error'` event is emitted if
     verification fails; `err.code` contains the OpenSSL error code. Defaults to
@@ -47,25 +34,79 @@ added: v0.11.3
     to be used when checking the server's hostname against the certificate.
     This should throw an error if verification fails. The method should return
     `undefined` if the `servername` and `cert` are verified.
-  * `secureProtocol` {string} The SSL method to use, e.g. `SSLv3_method` to
-    force SSL version 3. The possible values depend on the version of OpenSSL
-    installed in the environment and are defined in the constant
-    [SSL_METHODS][].
-  * `secureContext` {object} An optional TLS context object as returned by from
-    `tls.createSecureContext( ... )`. It can be used for caching client
-    certificates, keys, and CA certificates.
   * `session` {Buffer} A `Buffer` instance, containing TLS session.
   * `minDHSize` {number} Minimum size of the DH parameter in bits to accept a
     TLS connection. When a server offers a DH parameter with a size less
     than `minDHSize`, the TLS connection is destroyed and an error is thrown.
     Defaults to `1024`.
+  * `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
+    `tls.createSecureContext()`. *Note*: In effect, all
+    [`tls.createSecureContext()`][] options can be provided, but they will be
+    _completely ignored_ unless the `secureContext` option is missing.
+  * ...: Optional [`tls.createSecureContext()`][] options can be provided, see
+    the `secureContext` option for more information.
 * `callback` {Function}
 
-Creates a new client connection to the given `options.port` and `options.host`
-If `options.host` is omitted, it defaults to `localhost`.
-
 The `callback` function, if specified, will be added as a listener for the
 [`'secureConnect'`][] event.
 
 `tls.connect()` returns a [`tls.TLSSocket`][] object.
 
+The following implements a simple "echo server" example:
+
+```js
+const tls = require('tls');
+const fs = require('fs');
+
+const options = {
+  // Necessary only if using the client certificate authentication
+  key: fs.readFileSync('client-key.pem'),
+  cert: fs.readFileSync('client-cert.pem'),
+
+  // Necessary only if the server uses the self-signed certificate
+  ca: [ fs.readFileSync('server-cert.pem') ]
+};
+
+const socket = tls.connect(8000, options, () => {
+  console.log('client connected',
+              socket.authorized ? 'authorized' : 'unauthorized');
+  process.stdin.pipe(socket);
+  process.stdin.resume();
+});
+socket.setEncoding('utf8');
+socket.on('data', (data) => {
+  console.log(data);
+});
+socket.on('end', () => {
+  server.close();
+});
+```
+
+Or
+
+```js
+const tls = require('tls');
+const fs = require('fs');
+
+const options = {
+  pfx: fs.readFileSync('client.pfx')
+};
+
+const socket = tls.connect(8000, options, () => {
+  console.log('client connected',
+              socket.authorized ? 'authorized' : 'unauthorized');
+  process.stdin.pipe(socket);
+  process.stdin.resume();
+});
+socket.setEncoding('utf8');
+socket.on('data', (data) => {
+  console.log(data);
+});
+socket.on('end', () => {
+  server.close();
+});
+```
+
+

tls/tls_connect_path_options_callback.md

@@ -0,0 +1,14 @@
+<!-- YAML
+added: v0.11.3
+-->
+
+* `path` {string} Default value for `options.path`.
+* `options` {Object} See [`tls.connect()`][].
+* `callback` {Function} See [`tls.connect()`][].
+
+Same as [`tls.connect()`][] except that `path` can be provided
+as an argument instead of an option.
+
+*Note*: A path option, if specified, will take precedence over the path
+argument.
+

tls/tls_connect_port_host_options_callback.md

@@ -2,129 +2,14 @@
 added: v0.11.3
 -->
 
-* `port` {number}
-* `host` {string}
-* `options` {Object}
-  * `host` {string} Host the client should connect to.
-  * `port` {number} Port the client should connect to.
-  * `socket` {net.Socket} Establish secure connection on a given socket rather
-    than creating a new socket. If this option is specified, `host` and `port`
-    are ignored.
-  * `path` {string} Creates unix socket connection to path. If this option is
-    specified, `host` and `port` are ignored.
-  * `pfx` {string|Buffer} A string or `Buffer` containing the private key,
-    certificate, and CA certs of the client in PFX or PKCS12 format.
-  * `key` {string|string[]|Buffer|Buffer[]} A string, `Buffer`, array of
-    strings, or array of `Buffer`s containing the private key of the client in
-    PEM format.
-  * `passphrase` {string} A string containing the passphrase for the private key
-    or pfx.
-  * `cert` {string|string[]|Buffer|Buffer[]} A string, `Buffer`, array of
-    strings, or array of `Buffer`s containing the certificate key of the client
-    in PEM format.
-  * `ca` {string|string[]|Buffer|Buffer[]} A string, `Buffer`, array of strings,
-    or array of `Buffer`s of trusted certificates in PEM format. If this is
-    omitted several well known "root" CAs (like VeriSign) will be used. These
-    are used to authorize connections.
-  * `ciphers` {string} A string describing the ciphers to use or exclude,
-    separated by `:`. Uses the same default cipher suite as
-    [`tls.createServer()`][].
-  * `rejectUnauthorized` {boolean} If `true`, the server certificate is verified
-    against the list of supplied CAs. An `'error'` event is emitted if
-    verification fails; `err.code` contains the OpenSSL error code. Defaults to
-    `true`.
-  * `NPNProtocols` {string[]|Buffer[]} An array of strings or `Buffer`s
-    containing supported NPN protocols. `Buffer`s should have the format
-    `[len][name][len][name]...` e.g. `0x05hello0x05world`, where the first
-    byte is the length of the next protocol name. Passing an array is usually
-    much simpler, e.g. `['hello', 'world']`.
-  * `ALPNProtocols`: {string[]|Buffer[]} An array of strings or `Buffer`s
-    containing the supported ALPN protocols. `Buffer`s should have the format
-    `[len][name][len][name]...` e.g. `0x05hello0x05world`, where the first byte
-    is the length of the next protocol name. Passing an array is usually much
-    simpler: `['hello', 'world']`.)
-  * `servername`: {string} Server name for the SNI (Server Name Indication) TLS
-    extension.
-  * `checkServerIdentity(servername, cert)` {Function} A callback function
-    to be used when checking the server's hostname against the certificate.
-    This should throw an error if verification fails. The method should return
-    `undefined` if the `servername` and `cert` are verified.
-  * `secureProtocol` {string} The SSL method to use, e.g. `SSLv3_method` to
-    force SSL version 3. The possible values depend on the version of OpenSSL
-    installed in the environment and are defined in the constant
-    [SSL_METHODS][].
-  * `secureContext` {object} An optional TLS context object as returned by from
-    `tls.createSecureContext( ... )`. It can be used for caching client
-    certificates, keys, and CA certificates.
-  * `session` {Buffer} A `Buffer` instance, containing TLS session.
-  * `minDHSize` {number} Minimum size of the DH parameter in bits to accept a
-    TLS connection. When a server offers a DH parameter with a size less
-    than `minDHSize`, the TLS connection is destroyed and an error is thrown.
-    Defaults to `1024`.
-* `callback` {Function}
+* `port` {number} Default value for `options.port`.
+* `host` {string} Optional default value for `options.host`.
+* `options` {Object} See [`tls.connect()`][].
+* `callback` {Function} See [`tls.connect()`][].
 
-Creates a new client connection to the given `port` and `host` or
-`options.port` and `options.host`. (If `host` is omitted, it defaults to
-`localhost`.)
-
-The `callback` function, if specified, will be added as a listener for the
-[`'secureConnect'`][] event.
-
-`tls.connect()` returns a [`tls.TLSSocket`][] object.
-
-The following implements a simple "echo server" example:
-
-```js
-const tls = require('tls');
-const fs = require('fs');
-
-const options = {
-  // Necessary only if using the client certificate authentication
-  key: fs.readFileSync('client-key.pem'),
-  cert: fs.readFileSync('client-cert.pem'),
-
-  // Necessary only if the server uses the self-signed certificate
-  ca: [ fs.readFileSync('server-cert.pem') ]
-};
-
-const socket = tls.connect(8000, options, () => {
-  console.log('client connected',
-              socket.authorized ? 'authorized' : 'unauthorized');
-  process.stdin.pipe(socket);
-  process.stdin.resume();
-});
-socket.setEncoding('utf8');
-socket.on('data', (data) => {
-  console.log(data);
-});
-socket.on('end', () => {
-  server.close();
-});
-```
-
-Or
-
-```js
-const tls = require('tls');
-const fs = require('fs');
-
-const options = {
-  pfx: fs.readFileSync('client.pfx')
-};
-
-const socket = tls.connect(8000, options, () => {
-  console.log('client connected',
-              socket.authorized ? 'authorized' : 'unauthorized');
-  process.stdin.pipe(socket);
-  process.stdin.resume();
-});
-socket.setEncoding('utf8');
-socket.on('data', (data) => {
-  console.log(data);
-});
-socket.on('end', () => {
-  server.close();
-});
-```
+Same as [`tls.connect()`][] except that `port` and `host` can be provided
+as arguments instead of options.
 
+*Note*: A port or host option, if specified, will take precedence over any port
+or host argument.