doc: alphabetize tls options · nodejs/node@72e7e1d

-->

* `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

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

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

-->

* `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}