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

Jump to bottom

doc: remove _optional_ designation for tls options #22545

Closed
wants to merge 2 commits into from
Closed

doc: remove _optional_ designation for tls options #22545

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
90bc491
doc: remove _optional_ designation for tls options
Trott Aug 27, 2018
d92be8e
doc: indicate createSecureContext arg is optional
Trott Aug 27, 2018
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
122 changes: 60 additions & 62 deletions doc/api/tls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -905,13 +905,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}

Expand Down Expand Up @@ -995,7 +995,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()`][].

Expand All @@ -1005,7 +1005,7 @@ as arguments instead of options.
A port or host option, if specified, will take precedence over any port or host
argument.

## tls.createSecureContext(options)
## tls.createSecureContext([options])
<!-- YAML
added: v0.11.13
changes:
Expand Down Expand Up @@ -1039,23 +1039,23 @@ 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][].
Permitted ciphers can be obtained via [`tls.getCiphers()`][]. Cipher names
must be uppercased in order for OpenSSL to accept them.
* `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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure this is a good idea. It's hard to tell with options can be omitted now. It seems they must all be specified now.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I'm not mistaken, none of them are required. (If there were required things, it should probably be named config rather than options.) I think that by specifying "Optional" for some options, we mislead the reader into thinking that some options are required.

We have it called with an empty options object twice here.

I do think the function signature needs to be updated to put options in [] to make it clear that it can be omitted, like it is here and here.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do think the function signature needs to be updated

I've now done this in a separate commit. @vsemozhetbyt PTAL to confirm you're still 👍 on this with that addition. Thanks!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, but maybe let's get at least one LGTM from @nodejs/crypto to be on the safe side.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, but maybe let's get at least one LGTM from @nodejs/crypto to be on the safe side.

I'll remove the fast-track label, at least until that happens. No need to rush this.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nodejs/crypto Any chance someone can take a quick look at this?

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][]. Permitted
ciphers can be obtained via [`tls.getCiphers()`][]. Cipher names must be
uppercased in order for OpenSSL to accept them.
* `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
Expand All @@ -1073,19 +1073,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:
<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,
* `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: <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} 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: <string|buffer>[, passphrase: <string>]}`. The object form can only
Expand All @@ -1096,12 +1096,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.
Expand Down Expand Up @@ -1142,8 +1141,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
Expand Down Expand Up @@ -1328,16 +1327,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.
Expand Down