1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: remove _optional_ designation for tls options

Browse Source 
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 2018-08-26 19:12:53 -07:00 committed by Anna Henningsen
parent b4026099c3
commit 1672484b7e
No known key found for this signature in database
GPG Key ID: 9C63F3A6CD2AD8F9
1 changed files with 59 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

120
doc/api/tls.md
View File

@ -376,8 +376,8 @@ more information.
added: v0.3.2 added: v0.3.2
--> -->
* `callback` {Function} An optional listener callback that will be registered to * `callback` {Function} A listener callback that will be registered to listen
listen for the server instance's `'close'` event. for the server instance's `'close'` event.
The `server.close()` method stops the server from accepting new connections. 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 * `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 they are to behave as a server or a client. If `true` the TLS socket will be
instantiated as a server. **Default:** `false`. 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 * `requestCert`: Whether to authenticate the remote peer by requesting a
certificate. Clients always request a server certificate. Servers certificate. Clients always request a server certificate. Servers
(`isServer` is true) may optionally set `requestCert` to true to request a (`isServer` is true) may set `requestCert` to true to request a client
client certificate. certificate.
* `rejectUnauthorized`: Optional, see [`tls.createServer()`][] * `rejectUnauthorized`: See [`tls.createServer()`][]
* `ALPNProtocols`: Optional, see [`tls.createServer()`][] * `ALPNProtocols`: See [`tls.createServer()`][]
* `SNICallback`: Optional, see [`tls.createServer()`][] * `SNICallback`: See [`tls.createServer()`][]
* `session` {Buffer} An optional `Buffer` instance containing a TLS session. * `session` {Buffer} A `Buffer` instance containing a TLS session.
* `requestOCSP` {boolean} If `true`, specifies that the OCSP status request * `requestOCSP` {boolean} If `true`, specifies that the OCSP status request
extension will be added to the client hello and an `'OCSPResponse'` event extension will be added to the client hello and an `'OCSPResponse'` event
will be emitted on the socket before establishing a secure communication 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 [`tls.createSecureContext()`][]. If a `secureContext` is _not_ provided, one
will be created by passing the entire `options` object to will be created by passing the entire `options` object to
`tls.createSecureContext()`. `tls.createSecureContext()`.
* ...: 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. `secureContext` option is missing. Otherwise, they are ignored.
Construct a new `tls.TLSSocket` object from an existing TCP socket. 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 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. than `minDHSize`, the TLS connection is destroyed and an error is thrown.
**Default:** `1024`. **Default:** `1024`.
* `secureContext`: Optional TLS context object created with * `secureContext`: TLS context object created with
[`tls.createSecureContext()`][]. If a `secureContext` is _not_ provided, one [`tls.createSecureContext()`][]. If a `secureContext` is _not_ provided, one
will be created by passing the entire `options` object to will be created by passing the entire `options` object to
`tls.createSecureContext()`. `tls.createSecureContext()`.
* `lookup`: {Function} Custom lookup function. **Default:** * `lookup`: {Function} Custom lookup function. **Default:**
[`dns.lookup()`][]. [`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. `secureContext` option is missing, otherwise they are ignored.
* `callback` {Function} * `callback` {Function}
@ -993,7 +993,7 @@ added: v0.11.3
--> -->
* `port` {number} Default value for `options.port`. * `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()`][]. * `options` {Object} See [`tls.connect()`][].
* `callback` {Function} See [`tls.connect()`][]. * `callback` {Function} See [`tls.connect()`][].
@ -1037,23 +1037,23 @@ changes:
certificate can match or chain to. certificate can match or chain to.
For self-signed certificates, the certificate is its own CA, and must be For self-signed certificates, the certificate is its own CA, and must be
provided. provided.
* `cert` {string|string[]|Buffer|Buffer[]} Optional cert chains in PEM format. * `cert` {string|string[]|Buffer|Buffer[]} Cert chains in PEM format. One cert
One cert chain should be provided per private key. Each cert chain should chain should be provided per private key. Each cert chain should consist of
consist of the PEM formatted certificate for a provided private `key`, the PEM formatted certificate for a provided private `key`, followed by the
followed by the PEM formatted intermediate certificates (if any), in order, PEM formatted intermediate certificates (if any), in order, and not
and not including the root CA (the root CA must be pre-known to the peer, including the root CA (the root CA must be pre-known to the peer, see `ca`).
see `ca`). When providing multiple cert chains, they do not have to be in When providing multiple cert chains, they do not have to be in the same
the same order as their private keys in `key`. If the intermediate order as their private keys in `key`. If the intermediate certificates are
certificates are not provided, the peer will not be able to validate the not provided, the peer will not be able to validate the certificate, and the
certificate, and the handshake will fail. handshake will fail.
* `ciphers` {string} Optional cipher suite specification, replacing the * `ciphers` {string} Cipher suite specification, replacing the default. For
default. For more information, see [modifying the default cipher suite][]. more information, see [modifying the default cipher suite][]. Permitted
Permitted ciphers can be obtained via [`tls.getCiphers()`][]. Cipher names ciphers can be obtained via [`tls.getCiphers()`][]. Cipher names must be
must be uppercased in order for OpenSSL to accept them. uppercased in order for OpenSSL to accept them.
* `clientCertEngine` {string} Optional name of an OpenSSL engine which can * `clientCertEngine` {string} Name of an OpenSSL engine which can provide the
provide the client certificate. client certificate.
* `crl` {string|string[]|Buffer|Buffer[]} Optional PEM formatted * `crl` {string|string[]|Buffer|Buffer[]} PEM formatted CRLs (Certificate
CRLs (Certificate Revocation Lists). Revocation Lists).
* `dhparam` {string|Buffer} Diffie Hellman parameters, required for * `dhparam` {string|Buffer} Diffie Hellman parameters, required for
[Perfect Forward Secrecy][]. Use `openssl dhparam` to create the parameters. [Perfect Forward Secrecy][]. Use `openssl dhparam` to create the parameters.
The key length must be greater than or equal to 1024 bits, otherwise an 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 preferences instead of the client's. When `true`, causes
`SSL_OP_CIPHER_SERVER_PREFERENCE` to be set in `secureOptions`, see `SSL_OP_CIPHER_SERVER_PREFERENCE` to be set in `secureOptions`, see
[OpenSSL Options][] for more information. [OpenSSL Options][] for more information.
* `key` {string|string[]|Buffer|Buffer[]|Object[]} Optional private keys in * `key` {string|string[]|Buffer|Buffer[]|Object[]} Private keys in PEM format.
PEM format. PEM allows the option of private keys being encrypted. Encrypted PEM allows the option of private keys being encrypted. Encrypted keys will
keys will be decrypted with `options.passphrase`. Multiple keys using be decrypted with `options.passphrase`. Multiple keys using different
different algorithms can be provided either as an array of unencrypted key algorithms can be provided either as an array of unencrypted key strings or
strings or buffers, or an array of objects in the form `{pem: buffers, or an array of objects in the form `{pem: <string|buffer>[,
<string|buffer>[, passphrase: <string>]}`. The object form can only occur in passphrase: <string>]}`. The object form can only occur in an array.
an array. `object.passphrase` is optional. Encrypted keys will be decrypted `object.passphrase` is optional. Encrypted keys will be decrypted with
with `object.passphrase` if provided, or `options.passphrase` if it is not. `object.passphrase` if provided, or `options.passphrase` if it is not.
* `passphrase` {string} Optional shared passphrase used for a single private * `passphrase` {string} Shared passphrase used for a single private key and/or
key and/or a PFX. a PFX.
* `pfx` {string|string[]|Buffer|Buffer[]|Object[]} Optional PFX or PKCS12 * `pfx` {string|string[]|Buffer|Buffer[]|Object[]} PFX or PKCS12 encoded
encoded private key and certificate chain. `pfx` is an alternative to private key and certificate chain. `pfx` is an alternative to providing
providing `key` and `cert` individually. PFX is usually encrypted, if it is, `key` and `cert` individually. PFX is usually encrypted, if it is,
`passphrase` will be used to decrypt it. Multiple PFX can be provided either `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 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 `{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! which is not usually necessary. This should be used carefully if at all!
Value is a numeric bitmask of the `SSL_OP_*` options from Value is a numeric bitmask of the `SSL_OP_*` options from
[OpenSSL Options][]. [OpenSSL Options][].
* `secureProtocol` {string} Optional SSL method to use. The possible values * `secureProtocol` {string} SSL method to use. The possible values are listed
are listed as [SSL_METHODS][], use the function names as strings. as [SSL_METHODS][], use the function names as strings. For example,
For example, `'TLSv1_2_method'` to force TLS version 1.2. **Default:** `'TLSv1_2_method'` to force TLS version 1.2. **Default:** `'TLS_method'`.
`'TLS_method'`. * `sessionIdContext` {string} Opaque identifier used by servers to ensure
* `sessionIdContext` {string} Optional opaque identifier used by servers to session state is not shared between applications. Unused by clients.
ensure session state is not shared between applications. Unused by clients.
[`tls.createServer()`][] sets the default value of the `honorCipherOrder` option [`tls.createServer()`][] sets the default value of the `honorCipherOrder` option
to `true`, other APIs that create secure contexts leave it unset. 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 first byte is the length of the next protocol name. Passing an array is
usually much simpler, e.g. `['hello', 'world']`. usually much simpler, e.g. `['hello', 'world']`.
(Protocols should be ordered by their priority.) (Protocols should be ordered by their priority.)
* `clientCertEngine` {string} Optional name of an OpenSSL engine which can * `clientCertEngine` {string} Name of an OpenSSL engine which can provide the
provide the client certificate. client certificate.
* `handshakeTimeout` {number} Abort the connection if the SSL/TLS handshake * `handshakeTimeout` {number} Abort the connection if the SSL/TLS handshake
does not finish in the specified number of milliseconds. does not finish in the specified number of milliseconds.
A `'tlsClientError'` is emitted on the `tls.Server` object whenever A `'tlsClientError'` is emitted on the `tls.Server` object whenever
@ -1324,16 +1323,15 @@ changes:
* `rejectUnauthorized` {boolean} If not `false` a server automatically reject * `rejectUnauthorized` {boolean} If not `false` a server automatically reject
clients with invalid certificates. Only applies when `isServer` is `true`. clients with invalid certificates. Only applies when `isServer` is `true`.
* `options` * `options`
* `secureContext`: An optional TLS context object from * `secureContext`: A TLS context object from [`tls.createSecureContext()`][]
[`tls.createSecureContext()`][]
* `isServer`: If `true` the TLS socket will be instantiated in server-mode. * `isServer`: If `true` the TLS socket will be instantiated in server-mode.
**Default:** `false`. **Default:** `false`.
* `server` {net.Server} An optional [`net.Server`][] instance * `server` {net.Server} A [`net.Server`][] instance
* `requestCert`: Optional, see [`tls.createServer()`][] * `requestCert`: See [`tls.createServer()`][]
* `rejectUnauthorized`: Optional, see [`tls.createServer()`][] * `rejectUnauthorized`: See [`tls.createServer()`][]
* `ALPNProtocols`: Optional, see [`tls.createServer()`][] * `ALPNProtocols`: See [`tls.createServer()`][]
* `SNICallback`: Optional, see [`tls.createServer()`][] * `SNICallback`: See [`tls.createServer()`][]
* `session` {Buffer} An optional `Buffer` instance containing a TLS session. * `session` {Buffer} A `Buffer` instance containing a TLS session.
* `requestOCSP` {boolean} If `true`, specifies that the OCSP status request * `requestOCSP` {boolean} If `true`, specifies that the OCSP status request
extension will be added to the client hello and an `'OCSPResponse'` event extension will be added to the client hello and an `'OCSPResponse'` event
will be emitted on the socket before establishing a secure communication. will be emitted on the socket before establishing a secure communication.