Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: alphabetize tls options #21139

Closed
wants to merge 1 commit into from
Closed

doc: alphabetize tls options #21139

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 53 additions & 53 deletions doc/api/tls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1024,34 +1024,6 @@ changes:
-->

* `options` {Object}
* `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,
`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
occur in an array. `object.passphrase` is optional. Encrypted PFX will be
decrypted with `object.passphrase` if provided, or `options.passphrase` if
it is not.
* `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.
* `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.
* `ca` {string|string[]|Buffer|Buffer[]} Optionally override the trusted CA
certificates. Default is to trust the well-known CAs curated by Mozilla.
Mozilla's CAs are completely replaced when CAs are explicitly specified
Expand All @@ -1067,19 +1039,17 @@ 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][].
* `honorCipherOrder` {boolean} Attempt to use the server's cipher suite
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.
* `ecdhCurve` {string} A string describing a named curve or a colon separated
list of curve NIDs or names, for example `P-521:P-384:P-256`, to use for
ECDH key agreement, or `false` to disable ECDH. Set to `auto` to select the
curve automatically. Use [`crypto.getCurves()`][] to obtain a list of
available curve names. On recent releases, `openssl ecparam -list_curves`
will also display the name and description of each available elliptic curve.
**Default:** [`tls.DEFAULT_ECDH_CURVE`].
* `clientCertEngine` {string} Optional name of an OpenSSL engine which can
provide the client certificate.
* `crl` {string|string[]|Buffer|Buffer[]} Optional PEM formatted
Expand All @@ -1090,6 +1060,36 @@ changes:
error will be thrown. It is strongly recommended to use 2048 bits or larger
for stronger security. If omitted or invalid, the parameters are silently
discarded and DHE ciphers will not be available.
* `ecdhCurve` {string} A string describing a named curve or a colon separated
list of curve NIDs or names, for example `P-521:P-384:P-256`, to use for
ECDH key agreement, or `false` to disable ECDH. Set to `auto` to select the
curve automatically. Use [`crypto.getCurves()`][] to obtain a list of
available curve names. On recent releases, `openssl ecparam -list_curves`
will also display the name and description of each available elliptic curve.
**Default:** [`tls.DEFAULT_ECDH_CURVE`].
* `honorCipherOrder` {boolean} Attempt to use the server's cipher suite
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,
`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
occur in an array. `object.passphrase` is optional. Encrypted PFX will be
decrypted with `object.passphrase` if provided, or `options.passphrase` if
it is not.
* `secureOptions` {number} Optionally affect the OpenSSL protocol behavior,
which is not usually necessary. This should be used carefully if at all!
Value is a numeric bitmask of the `SSL_OP_*` options from
Expand Down Expand Up @@ -1133,38 +1133,38 @@ changes:
-->

* `options` {Object}
* `ALPNProtocols`: {string[]|Buffer[]|Uint8Array[]|Buffer|Uint8Array}
An array of strings, `Buffer`s or `Uint8Array`s, or a single `Buffer` or
`Uint8Array` containing the supported ALPN protocols. `Buffer`s should have
the format `[len][name][len][name]...` e.g. `0x05hello0x05world`, where the
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.
* `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
a handshake times out. **Default:** `120000` (120 seconds).
* `requestCert` {boolean} If `true` the server will request a certificate from
clients that connect and attempt to verify that certificate. **Default:**
`false`.
* `rejectUnauthorized` {boolean} If not `false` the server will reject any
connection which is not authorized with the list of supplied CAs. This
option only has an effect if `requestCert` is `true`. **Default:** `true`.
* `ALPNProtocols`: {string[]|Buffer[]|Uint8Array[]|Buffer|Uint8Array}
An array of strings, `Buffer`s or `Uint8Array`s, or a single `Buffer` or
`Uint8Array` containing the supported ALPN protocols. `Buffer`s should have
the format `[len][name][len][name]...` e.g. `0x05hello0x05world`, where the
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.)
* `requestCert` {boolean} If `true` the server will request a certificate from
clients that connect and attempt to verify that certificate. **Default:**
`false`.
* `sessionTimeout` {number} An integer specifying the number of seconds after
which the TLS session identifiers and TLS session tickets created by the
server will time out. See [`SSL_CTX_set_timeout`] for more details.
* `SNICallback(servername, cb)` {Function} A function that will be called if
the client supports SNI TLS extension. Two arguments will be passed when
called: `servername` and `cb`. `SNICallback` should invoke `cb(null, ctx)`,
where `ctx` is a `SecureContext` instance. (`tls.createSecureContext(...)`
can be used to get a proper `SecureContext`.) If `SNICallback` wasn't
provided the default callback with high-level API will be used (see below).
* `sessionTimeout` {number} An integer specifying the number of seconds after
which the TLS session identifiers and TLS session tickets created by the
server will time out. See [`SSL_CTX_set_timeout`] for more details.
* `ticketKeys`: A 48-byte `Buffer` instance consisting of a 16-byte prefix,
a 16-byte HMAC key, and a 16-byte AES key. This can be used to accept TLS
session tickets on multiple instances of the TLS server.
* ...: Any [`tls.createSecureContext()`][] options can be provided. For
* ...: Any [`tls.createSecureContext()`][] option can be provided. For
servers, the identity options (`pfx` or `key`/`cert`) are usually required.
* `secureConnectionListener` {Function}

Expand Down