mirror of
https://github.com/nodejs/node.git
synced 2024-12-01 16:10:02 +01:00
doc: remove _optional_ designation for tls options
Options are, by definition, optional. Remove specification of some options as "optional". PR-URL: https://github.com/nodejs/node/pull/22545 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: George Adams <george.adams@uk.ibm.com>
This commit is contained in:
Rich Trott
Anna Henningsen
parent
b4026099c3
commit
1672484b7e
120
doc/api/tls.md
120
doc/api/tls.md
@ -376,8 +376,8 @@ more information.
|
||||
added: v0.3.2
|
||||
-->
|
||||
|
||||
* `callback` {Function} An optional listener callback that will be registered to
|
||||
listen for the server instance's `'close'` event.
|
||||
* `callback` {Function} A listener callback that will be registered to listen
|
||||
for the server instance's `'close'` event.
|
||||
|
||||
The `server.close()` method stops the server from accepting new connections.
|
||||
|
||||
@ -458,24 +458,24 @@ changes:
|
||||
* `isServer`: The SSL/TLS protocol is asymmetrical, 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. **Default:** `false`.
|
||||
* `server` {net.Server} An optional [`net.Server`][] instance.
|
||||
* `server` {net.Server} A [`net.Server`][] instance.
|
||||
* `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()`][]
|
||||
* `ALPNProtocols`: Optional, see [`tls.createServer()`][]
|
||||
* `SNICallback`: Optional, see [`tls.createServer()`][]
|
||||
* `session` {Buffer} An optional `Buffer` instance containing a TLS session.
|
||||
(`isServer` is true) may set `requestCert` to true to request a client
|
||||
certificate.
|
||||
* `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
|
||||
* `secureContext`: Optional TLS context object created with
|
||||
* `secureContext`: 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()`.
|
||||
* ...: Optional [`tls.createSecureContext()`][] options that are used if the
|
||||
`secureContext` option is missing, otherwise they are ignored.
|
||||
* ...: [`tls.createSecureContext()`][] options that are used if the
|
||||
`secureContext` option is missing. Otherwise, they are ignored.
|
||||
|
||||
Construct a new `tls.TLSSocket` object from an existing TCP socket.
|
||||
|
||||
@ -903,13 +903,13 @@ changes:
|
||||
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.
|
||||
**Default:** `1024`.
|
||||
* `secureContext`: Optional TLS context object created with
|
||||
* `secureContext`: 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()`.
|
||||
* `lookup`: {Function} Custom lookup function. **Default:**
|
||||
[`dns.lookup()`][].
|
||||
* ...: Optional [`tls.createSecureContext()`][] options that are used if the
|
||||
* ...: [`tls.createSecureContext()`][] options that are used if the
|
||||
`secureContext` option is missing, otherwise they are ignored.
|
||||
* `callback` {Function}
|
||||
|
||||
@ -993,7 +993,7 @@ added: v0.11.3
|
||||
-->
|
||||
|
||||
* `port` {number} Default value for `options.port`.
|
||||
* `host` {string} Optional default value for `options.host`.
|
||||
* `host` {string} Default value for `options.host`.
|
||||
* `options` {Object} See [`tls.connect()`][].
|
||||
* `callback` {Function} See [`tls.connect()`][].
|
||||
|
||||
@ -1037,23 +1037,23 @@ changes:
|
||||
certificate can match or chain to.
|
||||
For self-signed certificates, the certificate is its own CA, and must be
|
||||
provided.
|
||||
* `cert` {string|string[]|Buffer|Buffer[]} Optional cert chains in PEM format.
|
||||
One cert chain should be provided per private key. Each cert chain should
|
||||
consist of the PEM formatted certificate for a provided private `key`,
|
||||
followed by the PEM formatted intermediate certificates (if any), in order,
|
||||
and not including the root CA (the root CA must be pre-known to the peer,
|
||||
see `ca`). When providing multiple cert chains, they do not have to be in
|
||||
the same order as their private keys in `key`. If the intermediate
|
||||
certificates are not provided, the peer will not be able to validate the
|
||||
certificate, and the handshake will fail.
|
||||
* `ciphers` {string} Optional cipher suite specification, replacing the
|
||||
default. For more information, see [modifying the default cipher suite][].
|
||||
Permitted ciphers can be obtained via [`tls.getCiphers()`][]. Cipher names
|
||||
must be uppercased in order for OpenSSL to accept them.
|
||||
* `clientCertEngine` {string} Optional name of an OpenSSL engine which can
|
||||
provide the client certificate.
|
||||
* `crl` {string|string[]|Buffer|Buffer[]} Optional PEM formatted
|
||||
CRLs (Certificate Revocation Lists).
|
||||
* `cert` {string|string[]|Buffer|Buffer[]} Cert chains in PEM format. One cert
|
||||
chain should be provided per private key. Each cert chain should consist of
|
||||
the PEM formatted certificate for a provided private `key`, followed by the
|
||||
PEM formatted intermediate certificates (if any), in order, and not
|
||||
including the root CA (the root CA must be pre-known to the peer, see `ca`).
|
||||
When providing multiple cert chains, they do not have to be in the same
|
||||
order as their private keys in `key`. If the intermediate certificates are
|
||||
not provided, the peer will not be able to validate the certificate, and the
|
||||
handshake will fail.
|
||||
* `ciphers` {string} Cipher suite specification, replacing the default. For
|
||||
more information, see [modifying the default cipher suite][]. Permitted
|
||||
ciphers can be obtained via [`tls.getCiphers()`][]. Cipher names must be
|
||||
uppercased in order for OpenSSL to accept them.
|
||||
* `clientCertEngine` {string} Name of an OpenSSL engine which can provide the
|
||||
client certificate.
|
||||
* `crl` {string|string[]|Buffer|Buffer[]} PEM formatted CRLs (Certificate
|
||||
Revocation Lists).
|
||||
* `dhparam` {string|Buffer} Diffie Hellman parameters, required for
|
||||
[Perfect Forward Secrecy][]. Use `openssl dhparam` to create the parameters.
|
||||
The key length must be greater than or equal to 1024 bits, otherwise an
|
||||
@ -1071,19 +1071,19 @@ changes:
|
||||
preferences instead of the client's. When `true`, causes
|
||||
`SSL_OP_CIPHER_SERVER_PREFERENCE` to be set in `secureOptions`, see
|
||||
[OpenSSL Options][] for more information.
|
||||
* `key` {string|string[]|Buffer|Buffer[]|Object[]} Optional private keys in
|
||||
PEM format. PEM allows the option of private keys being encrypted. Encrypted
|
||||
keys will be decrypted with `options.passphrase`. Multiple keys using
|
||||
different algorithms can be provided either as an array of unencrypted key
|
||||
strings or buffers, or an array of objects in the form `{pem:
|
||||
<string|buffer>[, passphrase: <string>]}`. The object form can only occur in
|
||||
an array. `object.passphrase` is optional. Encrypted keys will be decrypted
|
||||
with `object.passphrase` if provided, or `options.passphrase` if it is not.
|
||||
* `passphrase` {string} Optional shared passphrase used for a single private
|
||||
key and/or a PFX.
|
||||
* `pfx` {string|string[]|Buffer|Buffer[]|Object[]} Optional PFX or PKCS12
|
||||
encoded private key and certificate chain. `pfx` is an alternative to
|
||||
providing `key` and `cert` individually. PFX is usually encrypted, if it is,
|
||||
* `key` {string|string[]|Buffer|Buffer[]|Object[]} Private keys in PEM format.
|
||||
PEM allows the option of private keys being encrypted. Encrypted keys will
|
||||
be decrypted with `options.passphrase`. Multiple keys using different
|
||||
algorithms can be provided either as an array of unencrypted key strings or
|
||||
buffers, or an array of objects in the form `{pem: <string|buffer>[,
|
||||
passphrase: <string>]}`. The object form can only occur in an array.
|
||||
`object.passphrase` is optional. Encrypted keys will be decrypted with
|
||||
`object.passphrase` if provided, or `options.passphrase` if it is not.
|
||||
* `passphrase` {string} Shared passphrase used for a single private key and/or
|
||||
a PFX.
|
||||
* `pfx` {string|string[]|Buffer|Buffer[]|Object[]} PFX or PKCS12 encoded
|
||||
private key and certificate chain. `pfx` is an alternative to providing
|
||||
`key` and `cert` individually. PFX is usually encrypted, if it is,
|
||||
`passphrase` will be used to decrypt it. Multiple PFX can be provided either
|
||||
as an array of unencrypted PFX buffers, or an array of objects in the form
|
||||
`{buf: <string|buffer>[, passphrase: <string>]}`. The object form can only
|
||||
@ -1094,12 +1094,11 @@ changes:
|
||||
which is not usually necessary. This should be used carefully if at all!
|
||||
Value is a numeric bitmask of the `SSL_OP_*` options from
|
||||
[OpenSSL Options][].
|
||||
* `secureProtocol` {string} Optional SSL method to use. The possible values
|
||||
are listed as [SSL_METHODS][], use the function names as strings.
|
||||
For example, `'TLSv1_2_method'` to force TLS version 1.2. **Default:**
|
||||
`'TLS_method'`.
|
||||
* `sessionIdContext` {string} Optional opaque identifier used by servers to
|
||||
ensure session state is not shared between applications. Unused by clients.
|
||||
* `secureProtocol` {string} SSL method to use. The possible values are listed
|
||||
as [SSL_METHODS][], use the function names as strings. For example,
|
||||
`'TLSv1_2_method'` to force TLS version 1.2. **Default:** `'TLS_method'`.
|
||||
* `sessionIdContext` {string} Opaque identifier used by servers to ensure
|
||||
session state is not shared between applications. Unused by clients.
|
||||
|
||||
[`tls.createServer()`][] sets the default value of the `honorCipherOrder` option
|
||||
to `true`, other APIs that create secure contexts leave it unset.
|
||||
@ -1140,8 +1139,8 @@ changes:
|
||||
first byte is the length of the next protocol name. Passing an array is
|
||||
usually much simpler, e.g. `['hello', 'world']`.
|
||||
(Protocols should be ordered by their priority.)
|
||||
* `clientCertEngine` {string} Optional name of an OpenSSL engine which can
|
||||
provide the client certificate.
|
||||
* `clientCertEngine` {string} Name of an OpenSSL engine which can provide the
|
||||
client certificate.
|
||||
* `handshakeTimeout` {number} Abort the connection if the SSL/TLS handshake
|
||||
does not finish in the specified number of milliseconds.
|
||||
A `'tlsClientError'` is emitted on the `tls.Server` object whenever
|
||||
@ -1324,16 +1323,15 @@ changes:
|
||||
* `rejectUnauthorized` {boolean} If not `false` a server automatically reject
|
||||
clients with invalid certificates. Only applies when `isServer` is `true`.
|
||||
* `options`
|
||||
* `secureContext`: An optional TLS context object from
|
||||
[`tls.createSecureContext()`][]
|
||||
* `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} An optional [`net.Server`][] instance
|
||||
* `requestCert`: Optional, see [`tls.createServer()`][]
|
||||
* `rejectUnauthorized`: Optional, see [`tls.createServer()`][]
|
||||
* `ALPNProtocols`: Optional, see [`tls.createServer()`][]
|
||||
* `SNICallback`: Optional, see [`tls.createServer()`][]
|
||||
* `session` {Buffer} An optional `Buffer` instance containing a TLS session.
|
||||
* `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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user