Skip to content

Commit

Permalink
doc: reorder deprecated tls docs
Browse files Browse the repository at this point in the history 
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: #34687
Reviewed-By: Rich Trott <rtrott@gmail.com>
  • Loading branch information
@jeromecovington @addaleax
jeromecovington authored and addaleax committed Sep 22, 2020
1 parent edda492 commit c53c34c
Show file tree
Hide file tree
Showing 2 changed files with 110 additions and 112 deletions.
4 changes: 2 additions & 2 deletions doc/api/deprecations.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
218 changes: 108 additions & 110 deletions doc/api/tls.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`
<!-- YAML
added: v0.3.4
deprecated: v0.11.3
-->

> 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`
<!-- YAML
added: v0.3.4
deprecated: v0.11.3
-->

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`
<!-- YAML
added: v0.3.2
deprecated: v0.11.3
-->

> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
Returned by [`tls.createSecurePair()`][].

### Event: `'secure'`
<!-- YAML
added: v0.3.2
deprecated: v0.11.3
-->

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`
<!-- YAML
added: v0.3.2
Expand Down Expand Up @@ -1657,6 +1702,69 @@ A key is *required* for ciphers that make use of certificates. Either `key` or
If the `ca` option is not given, then Node.js will default to using
[Mozilla's publicly trusted list of CAs][].

## `tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options])`
<!-- YAML
added: v0.3.2
deprecated: v0.11.3
changes:
- version: v5.0.0
pr-url: https://github.com/nodejs/node/pull/2564
description: ALPN options are supported now.
-->

> 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])`
<!-- YAML
added: v0.3.2
Expand Down Expand Up @@ -1853,116 +1961,6 @@ added: v11.4.0
`'TLSv1.3'`. If multiple of the options are provided, the lowest minimum is
used.

## Deprecated APIs

### Class: `CryptoStream`
<!-- YAML
added: v0.3.4
deprecated: v0.11.3
-->

> 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`
<!-- YAML
added: v0.3.4
deprecated: v0.11.3
-->

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`
<!-- YAML
added: v0.3.2
deprecated: v0.11.3
-->

> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
Returned by [`tls.createSecurePair()`][].

#### Event: `'secure'`
<!-- YAML
added: v0.3.2
deprecated: v0.11.3
-->

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])`
<!-- YAML
added: v0.3.2
deprecated: v0.11.3
changes:
- version: v5.0.0
pr-url: https://github.com/nodejs/node/pull/2564
description: ALPN options are supported now.
-->

> 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
Expand Down

0 comments on commit c53c34c

Please sign in to comment.