From 72e7e1da2d2eceaebee8e7205c3bb53237ed7f5c Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Mon, 4 Jun 2018 12:23:26 -0700 Subject: [PATCH] doc: alphabetize tls options MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Alphabetize the lists of options for tls.createServer() and tls.createSecureContext(). PR-URL: https://github.com/nodejs/node/pull/21139 Reviewed-By: Trivikram Kamat Reviewed-By: Michaël Zasso Reviewed-By: Luigi Pinca Reviewed-By: Colin Ihrig Reviewed-By: Vse Mozhet Byt --- doc/api/tls.md | 106 ++++++++++++++++++++++++------------------------- 1 file changed, 53 insertions(+), 53 deletions(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index 0e1cf39c2bcd31..9d713088879927 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -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: [, passphrase: ]}`. 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: - [, passphrase: ]}`. 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 @@ -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 @@ -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: + [, passphrase: ]}`. 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: [, passphrase: ]}`. 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 @@ -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}