From 0e862da42272bbe20b625e947a45a5a6bd152a73 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 26 Aug 2018 19:12:53 -0700 Subject: [PATCH] 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 Reviewed-By: Luigi Pinca Reviewed-By: Trivikram Kamat Reviewed-By: James M Snell Reviewed-By: George Adams --- doc/api/tls.md | 116 ++++++++++++++++++++++++------------------------- 1 file changed, 57 insertions(+), 59 deletions(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index ecc5ddd61da4dc..bc5e1b416f2c3d 100644 --- a/doc/api/tls.md +++ b/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,21 +1037,21 @@ 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][]. - * `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][]. + * `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 @@ -1069,19 +1069,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: - [, 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, + * `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: [, + 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} 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: [, passphrase: ]}`. The object form can only @@ -1092,12 +1092,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. @@ -1138,8 +1137,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 @@ -1322,16 +1321,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.