diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index fe7eb21c3cd295..c5e28557a515c4 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -2853,9 +2853,9 @@ Type: Documentation-only [`timeout.ref()`]: timers.html#timers_timeout_ref [`timeout.refresh()`]: timers.html#timers_timeout_refresh [`timeout.unref()`]: timers.html#timers_timeout_unref -[`tls.CryptoStream`]: tls.html#tls_class_cryptostream +[`tls.CryptoStream`]: tls.html#tls_class_tls_cryptostream [`tls.SecureContext`]: tls.html#tls_tls_createsecurecontext_options -[`tls.SecurePair`]: tls.html#tls_class_securepair +[`tls.SecurePair`]: tls.html#tls_class_tls_securepair [`tls.TLSSocket`]: tls.html#tls_class_tls_tlssocket [`tls.checkServerIdentity()`]: tls.html#tls_tls_checkserveridentity_hostname_cert [`tls.createSecureContext()`]: tls.html#tls_tls_createsecurecontext_options diff --git a/doc/api/tls.md b/doc/api/tls.md index 28c72a52342825..e0eef0d71ac5a7 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -370,6 +370,51 @@ The first 3 are enabled by default. The last 2 `CCM`-based suites are supported by TLSv1.3 because they may be more performant on constrained systems, but they are not enabled by default since they offer less security. +## Class: `tls.CryptoStream` + + +> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead. + +The `tls.CryptoStream` class represents a stream of encrypted data. This class +is deprecated and should no longer be used. + +### `cryptoStream.bytesWritten` + + +The `cryptoStream.bytesWritten` property returns the total number of bytes +written to the underlying socket *including* the bytes required for the +implementation of the TLS protocol. + +## Class: `tls.SecurePair` + + +> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead. + +Returned by [`tls.createSecurePair()`][]. + +### Event: `'secure'` + + +The `'secure'` event is emitted by the `SecurePair` object once a secure +connection has been established. + +As with checking for the server +[`'secureConnection'`](#tls_event_secureconnection) +event, `pair.cleartext.authorized` should be inspected to confirm whether the +certificate used is properly authorized. + ## Class: `tls.Server` + +> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead. + +* `context` {Object} A secure context object as returned by + `tls.createSecureContext()` +* `isServer` {boolean} `true` to specify that this TLS connection should be + opened as a server. +* `requestCert` {boolean} `true` to specify whether a server should request a + certificate from a connecting client. Only applies when `isServer` is `true`. +* `rejectUnauthorized` {boolean} If not `false` a server automatically reject + clients with invalid certificates. Only applies when `isServer` is `true`. +* `options` + * `enableTrace`: See [`tls.createServer()`][] + * `secureContext`: A TLS context object from [`tls.createSecureContext()`][] + * `isServer`: If `true` the TLS socket will be instantiated in server-mode. + **Default:** `false`. + * `server` {net.Server} A [`net.Server`][] instance + * `requestCert`: See [`tls.createServer()`][] + * `rejectUnauthorized`: See [`tls.createServer()`][] + * `ALPNProtocols`: See [`tls.createServer()`][] + * `SNICallback`: See [`tls.createServer()`][] + * `session` {Buffer} A `Buffer` instance containing a TLS session. + * `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. + +Creates a new secure pair object with two streams, one of which reads and writes +the encrypted data and the other of which reads and writes the cleartext data. +Generally, the encrypted stream is piped to/from an incoming encrypted data +stream and the cleartext one is used as a replacement for the initial encrypted +stream. + +`tls.createSecurePair()` returns a `tls.SecurePair` object with `cleartext` and +`encrypted` stream properties. + +Using `cleartext` has the same API as [`tls.TLSSocket`][]. + +The `tls.createSecurePair()` method is now deprecated in favor of +`tls.TLSSocket()`. For example, the code: + +```js +pair = tls.createSecurePair(/* ... */); +pair.encrypted.pipe(socket); +socket.pipe(pair.encrypted); +``` + +can be replaced by: + +```js +secureSocket = tls.TLSSocket(socket, options); +``` + +where `secureSocket` has the same API as `pair.cleartext`. + ## `tls.createServer([options][, secureConnectionListener])` - -> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead. - -The `tls.CryptoStream` class represents a stream of encrypted data. This class -is deprecated and should no longer be used. - -#### `cryptoStream.bytesWritten` - - -The `cryptoStream.bytesWritten` property returns the total number of bytes -written to the underlying socket *including* the bytes required for the -implementation of the TLS protocol. - -### Class: `SecurePair` - - -> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead. - -Returned by [`tls.createSecurePair()`][]. - -#### Event: `'secure'` - - -The `'secure'` event is emitted by the `SecurePair` object once a secure -connection has been established. - -As with checking for the server -[`'secureConnection'`](#tls_event_secureconnection) -event, `pair.cleartext.authorized` should be inspected to confirm whether the -certificate used is properly authorized. - -### `tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options])` - - -> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead. - -* `context` {Object} A secure context object as returned by - `tls.createSecureContext()` -* `isServer` {boolean} `true` to specify that this TLS connection should be - opened as a server. -* `requestCert` {boolean} `true` to specify whether a server should request a - certificate from a connecting client. Only applies when `isServer` is `true`. -* `rejectUnauthorized` {boolean} If not `false` a server automatically reject - clients with invalid certificates. Only applies when `isServer` is `true`. -* `options` - * `enableTrace`: See [`tls.createServer()`][] - * `secureContext`: A TLS context object from [`tls.createSecureContext()`][] - * `isServer`: If `true` the TLS socket will be instantiated in server-mode. - **Default:** `false`. - * `server` {net.Server} A [`net.Server`][] instance - * `requestCert`: See [`tls.createServer()`][] - * `rejectUnauthorized`: See [`tls.createServer()`][] - * `ALPNProtocols`: See [`tls.createServer()`][] - * `SNICallback`: See [`tls.createServer()`][] - * `session` {Buffer} A `Buffer` instance containing a TLS session. - * `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. - -Creates a new secure pair object with two streams, one of which reads and writes -the encrypted data and the other of which reads and writes the cleartext data. -Generally, the encrypted stream is piped to/from an incoming encrypted data -stream and the cleartext one is used as a replacement for the initial encrypted -stream. - -`tls.createSecurePair()` returns a `tls.SecurePair` object with `cleartext` and -`encrypted` stream properties. - -Using `cleartext` has the same API as [`tls.TLSSocket`][]. - -The `tls.createSecurePair()` method is now deprecated in favor of -`tls.TLSSocket()`. For example, the code: - -```js -pair = tls.createSecurePair(/* ... */); -pair.encrypted.pipe(socket); -socket.pipe(pair.encrypted); -``` - -can be replaced by: - -```js -secureSocket = tls.TLSSocket(socket, options); -``` - -where `secureSocket` has the same API as `pair.cleartext`. - [`'newSession'`]: #tls_event_newsession [`'resumeSession'`]: #tls_event_resumesession [`'secureConnect'`]: #tls_event_secureconnect