FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

doc: reorder deprecated tls docs · nodejs/node@b356b79 · GitHub

/ node Public

Commit b356b79

Browse files
jeromecovington
authored and
BethGriggs
committed
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: #34687 Reviewed-By: Rich Trott <rtrott@gmail.com>
1 parent 5c987ff commit b356b79

2 files changed

Lines changed: 110 additions & 112 deletions

File tree

‎doc/api/deprecations.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2846,9 +2846,9 @@ The [`crypto.Certificate()` constructor][] is deprecated. Use
28462846
[`timeout.ref()`]: timers.html#timers_timeout_ref
28472847
[`timeout.refresh()`]: timers.html#timers_timeout_refresh
28482848
[`timeout.unref()`]: timers.html#timers_timeout_unref
2849-
[`tls.CryptoStream`]: tls.html#tls_class_cryptostream
2849+
[`tls.CryptoStream`]: tls.html#tls_class_tls_cryptostream
28502850
[`tls.SecureContext`]: tls.html#tls_tls_createsecurecontext_options
2851-
[`tls.SecurePair`]: tls.html#tls_class_securepair
2851+
[`tls.SecurePair`]: tls.html#tls_class_tls_securepair
28522852
[`tls.TLSSocket`]: tls.html#tls_class_tls_tlssocket
28532853
[`tls.checkServerIdentity()`]: tls.html#tls_tls_checkserveridentity_hostname_cert
28542854
[`tls.createSecureContext()`]: tls.html#tls_tls_createsecurecontext_options

‎doc/api/tls.md‎

Lines changed: 108 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -370,6 +370,51 @@ The first 3 are enabled by default. The last 2 `CCM`-based suites are supported
370370
by TLSv1.3 because they may be more performant on constrained systems, but they
371371
are not enabled by default since they offer less security.
372372

373+
## Class: `tls.CryptoStream`
374+
<!-- YAML
375+
added: v0.3.4
376+
deprecated: v0.11.3
377+
-->
378+
379+
> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
380+
381+
The `tls.CryptoStream` class represents a stream of encrypted data. This class
382+
is deprecated and should no longer be used.
383+
384+
### `cryptoStream.bytesWritten`
385+
<!-- YAML
386+
added: v0.3.4
387+
deprecated: v0.11.3
388+
-->
389+
390+
The `cryptoStream.bytesWritten` property returns the total number of bytes
391+
written to the underlying socket *including* the bytes required for the
392+
implementation of the TLS protocol.
393+
394+
## Class: `tls.SecurePair`
395+
<!-- YAML
396+
added: v0.3.2
397+
deprecated: v0.11.3
398+
-->
399+
400+
> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
401+
402+
Returned by [`tls.createSecurePair()`][].
403+
404+
### Event: `'secure'`
405+
<!-- YAML
406+
added: v0.3.2
407+
deprecated: v0.11.3
408+
-->
409+
410+
The `'secure'` event is emitted by the `SecurePair` object once a secure
411+
connection has been established.
412+
413+
As with checking for the server
414+
[`'secureConnection'`](#tls_event_secureconnection)
415+
event, `pair.cleartext.authorized` should be inspected to confirm whether the
416+
certificate used is properly authorized.
417+
373418
## Class: `tls.Server`
374419
<!-- YAML
375420
added: v0.3.2
@@ -1679,6 +1724,69 @@ A key is *required* for ciphers that make use of certificates. Either `key` or
16791724
If the `ca` option is not given, then Node.js will default to using
16801725
[Mozilla's publicly trusted list of CAs][].
16811726

1727+
## `tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options])`
1728+
<!-- YAML
1729+
added: v0.3.2
1730+
deprecated: v0.11.3
1731+
changes:
1732+
- version: v5.0.0
1733+
pr-url: https://github.com/nodejs/node/pull/2564
1734+
description: ALPN options are supported now.
1735+
-->
1736+
1737+
> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
1738+
1739+
* `context` {Object} A secure context object as returned by
1740+
`tls.createSecureContext()`
1741+
* `isServer` {boolean} `true` to specify that this TLS connection should be
1742+
opened as a server.
1743+
* `requestCert` {boolean} `true` to specify whether a server should request a
1744+
certificate from a connecting client. Only applies when `isServer` is `true`.
1745+
* `rejectUnauthorized` {boolean} If not `false` a server automatically reject
1746+
clients with invalid certificates. Only applies when `isServer` is `true`.
1747+
* `options`
1748+
* `enableTrace`: See [`tls.createServer()`][]
1749+
* `secureContext`: A TLS context object from [`tls.createSecureContext()`][]
1750+
* `isServer`: If `true` the TLS socket will be instantiated in server-mode.
1751+
**Default:** `false`.
1752+
* `server` {net.Server} A [`net.Server`][] instance
1753+
* `requestCert`: See [`tls.createServer()`][]
1754+
* `rejectUnauthorized`: See [`tls.createServer()`][]
1755+
* `ALPNProtocols`: See [`tls.createServer()`][]
1756+
* `SNICallback`: See [`tls.createServer()`][]
1757+
* `session` {Buffer} A `Buffer` instance containing a TLS session.
1758+
* `requestOCSP` {boolean} If `true`, specifies that the OCSP status request
1759+
extension will be added to the client hello and an `'OCSPResponse'` event
1760+
will be emitted on the socket before establishing a secure communication.
1761+
1762+
Creates a new secure pair object with two streams, one of which reads and writes
1763+
the encrypted data and the other of which reads and writes the cleartext data.
1764+
Generally, the encrypted stream is piped to/from an incoming encrypted data
1765+
stream and the cleartext one is used as a replacement for the initial encrypted
1766+
stream.
1767+
1768+
`tls.createSecurePair()` returns a `tls.SecurePair` object with `cleartext` and
1769+
`encrypted` stream properties.
1770+
1771+
Using `cleartext` has the same API as [`tls.TLSSocket`][].
1772+
1773+
The `tls.createSecurePair()` method is now deprecated in favor of
1774+
`tls.TLSSocket()`. For example, the code:
1775+
1776+
```js
1777+
pair = tls.createSecurePair(/* ... */);
1778+
pair.encrypted.pipe(socket);
1779+
socket.pipe(pair.encrypted);
1780+
```
1781+
1782+
can be replaced by:
1783+
1784+
```js
1785+
secureSocket = tls.TLSSocket(socket, options);
1786+
```
1787+
1788+
where `secureSocket` has the same API as `pair.cleartext`.
1789+
16821790
## `tls.createServer([options][, secureConnectionListener])`
16831791
<!-- YAML
16841792
added: v0.3.2
@@ -1875,116 +1983,6 @@ added: v11.4.0
18751983
`'TLSv1.3'`. If multiple of the options are provided, the lowest minimum is
18761984
used.
18771985

1878-
## Deprecated APIs
1879-
1880-
### Class: `CryptoStream`
1881-
<!-- YAML
1882-
added: v0.3.4
1883-
deprecated: v0.11.3
1884-
-->
1885-
1886-
> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
1887-
1888-
The `tls.CryptoStream` class represents a stream of encrypted data. This class
1889-
is deprecated and should no longer be used.
1890-
1891-
#### `cryptoStream.bytesWritten`
1892-
<!-- YAML
1893-
added: v0.3.4
1894-
deprecated: v0.11.3
1895-
-->
1896-
1897-
The `cryptoStream.bytesWritten` property returns the total number of bytes
1898-
written to the underlying socket *including* the bytes required for the
1899-
implementation of the TLS protocol.
1900-
1901-
### Class: `SecurePair`
1902-
<!-- YAML
1903-
added: v0.3.2
1904-
deprecated: v0.11.3
1905-
-->
1906-
1907-
> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
1908-
1909-
Returned by [`tls.createSecurePair()`][].
1910-
1911-
#### Event: `'secure'`
1912-
<!-- YAML
1913-
added: v0.3.2
1914-
deprecated: v0.11.3
1915-
-->
1916-
1917-
The `'secure'` event is emitted by the `SecurePair` object once a secure
1918-
connection has been established.
1919-
1920-
As with checking for the server
1921-
[`'secureConnection'`](#tls_event_secureconnection)
1922-
event, `pair.cleartext.authorized` should be inspected to confirm whether the
1923-
certificate used is properly authorized.
1924-
1925-
### `tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options])`
1926-
<!-- YAML
1927-
added: v0.3.2
1928-
deprecated: v0.11.3
1929-
changes:
1930-
- version: v5.0.0
1931-
pr-url: https://github.com/nodejs/node/pull/2564
1932-
description: ALPN options are supported now.
1933-
-->
1934-
1935-
> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
1936-
1937-
* `context` {Object} A secure context object as returned by
1938-
`tls.createSecureContext()`
1939-
* `isServer` {boolean} `true` to specify that this TLS connection should be
1940-
opened as a server.
1941-
* `requestCert` {boolean} `true` to specify whether a server should request a
1942-
certificate from a connecting client. Only applies when `isServer` is `true`.
1943-
* `rejectUnauthorized` {boolean} If not `false` a server automatically reject
1944-
clients with invalid certificates. Only applies when `isServer` is `true`.
1945-
* `options`
1946-
* `enableTrace`: See [`tls.createServer()`][]
1947-
* `secureContext`: A TLS context object from [`tls.createSecureContext()`][]
1948-
* `isServer`: If `true` the TLS socket will be instantiated in server-mode.
1949-
**Default:** `false`.
1950-
* `server` {net.Server} A [`net.Server`][] instance
1951-
* `requestCert`: See [`tls.createServer()`][]
1952-
* `rejectUnauthorized`: See [`tls.createServer()`][]
1953-
* `ALPNProtocols`: See [`tls.createServer()`][]
1954-
* `SNICallback`: See [`tls.createServer()`][]
1955-
* `session` {Buffer} A `Buffer` instance containing a TLS session.
1956-
* `requestOCSP` {boolean} If `true`, specifies that the OCSP status request
1957-
extension will be added to the client hello and an `'OCSPResponse'` event
1958-
will be emitted on the socket before establishing a secure communication.
1959-
1960-
Creates a new secure pair object with two streams, one of which reads and writes
1961-
the encrypted data and the other of which reads and writes the cleartext data.
1962-
Generally, the encrypted stream is piped to/from an incoming encrypted data
1963-
stream and the cleartext one is used as a replacement for the initial encrypted
1964-
stream.
1965-
1966-
`tls.createSecurePair()` returns a `tls.SecurePair` object with `cleartext` and
1967-
`encrypted` stream properties.
1968-
1969-
Using `cleartext` has the same API as [`tls.TLSSocket`][].
1970-
1971-
The `tls.createSecurePair()` method is now deprecated in favor of
1972-
`tls.TLSSocket()`. For example, the code:
1973-
1974-
```js
1975-
pair = tls.createSecurePair(/* ... */);
1976-
pair.encrypted.pipe(socket);
1977-
socket.pipe(pair.encrypted);
1978-
```
1979-
1980-
can be replaced by:
1981-
1982-
```js
1983-
secureSocket = tls.TLSSocket(socket, options);
1984-
```
1985-
1986-
where `secureSocket` has the same API as `pair.cleartext`.
1987-
19881986
[`'newSession'`]: #tls_event_newsession
19891987
[`'resumeSession'`]: #tls_event_resumesession
19901988
[`'secureConnect'`]: #tls_event_secureconnect

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL