From c53c34c04581c5353a6e7c01fee2dea96cab33f9 Mon Sep 17 00:00:00 2001 From: "Jerome T.K. Covington" Date: Sat, 8 Aug 2020 20:17:01 -0400 Subject: [PATCH] doc: reorder deprecated tls docs In other api docs, it seems that deprecated classes and methods are listed along with others, and marked as deprecated. In tls docs, deprecations were listed at the bottom of the document. This commit reorders them to what seems to be the standard, and corrects some links in doc/api/deprecations.md PR-URL: https://github.com/nodejs/node/pull/34687 Reviewed-By: Rich Trott --- doc/api/deprecations.md | 4 +- doc/api/tls.md | 218 ++++++++++++++++++++-------------------- 2 files changed, 110 insertions(+), 112 deletions(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index a12ca3dd7b5626..51203074ce3d19 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -2664,9 +2664,9 @@ const moduleParents = Object.values(require.cache) [`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 a55b52746b4207..5fb309d4caa052 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