docs(NODE-4778): update tls option notes

[durran]

Description

Updates the TLS comments in MongoClient to note the spec compliant options, that others will be deprecated and removed, and fixed the type comments on the existing options.

What is changing?

Is there new documentation needed for these changes?

What is the motivation for this change?

NODE-4778

Double check the following

• Ran npm run check:lint script
• Self-review completed using the steps outlined here
• PR title follows the correct format: type(NODE-xxxx)[!]: description
  • Example: feat(NODE-1234)!: rewriting everything in coffeescript
• Changes are covered by tests
• New TODOs have a related JIRA ticket

[dariakp]

This comment will be public facing, since it's on the public interface, so we probably want to rephrase it in a way that makes sense to a user reading this (and take care of the typo in the tlsCertificateKeyFilePassword). Additionally, tlsAllowInvalidCertificates, tlsAllowInvalidCertificates, and tlsInsecure aren't in the table below, so we should document them.

It might be most user-friendly to update the table heading from MongoDB equivalent to MongoDB driver spec equivalent and then add a column for Legacy option name (or something along those lines) instead of just listing them in the paragraph above, that way it's easy to see what maps to what.

Lastly, crl will no longer have an equivalent config option if we deprecate the sslCRL option - are we ok not letting users set it at all, or do we still need to provide some way for users to set it even if the drivers spec doesn't account for it?

[durran]

I've update the table per the suggestion. As for crl/sslCRL - @addaleax @dariakp if shell feels that we do still need support for it, even though it's not in the spec I think it's fine to not deprecate it. Maybe we can update the deprecation ticket to also add a more "spec compliant looking" name like tlsCRL so they all have the same naming convention?

[addaleax]

Are you sure you want to remove support for passing Node.js-specific types (Buffer | Buffer[] | KeyObject[])? IIUC drivers have some liberty to provide options in a more language-specific idiomatic way if you want.

(I do share the concern about crl. I don’t know how many people use it but it’s something we expose in the shell.)

[addaleax]

Suggested change

	* Spec complicant options: ssl, tls, tlsCAFile, tlsCertificateKeyFile, tlsCertificateKeyFilePassworda, tlsAllowInvalidCertificates,
	* Spec complicant options: ssl, tls, tlsCAFile, tlsCertificateKeyFile, tlsCertificateKeyFilePassword, tlsAllowInvalidCertificates,

[durran]

Typo fixed in table.

[dariakp]

Are you sure you want to remove support for passing Node.js-specific types (Buffer | Buffer[] | KeyObject[])? IIUC drivers have some liberty to provide options in a more language-specific idiomatic way if you want.

@addaleax This is not removing support for buffer, it's just updating the documentation to match reality. The buffer way of passing these into the client is not currently supported either in the types (which only list string) or in the actual parsing logic, which assumes it's a string pointing to the location of the files fs.readFileSync(String(value), { encoding: 'ascii' }). Moreover, NODE-3924 is going to further update this logic to make the certificate file reading happen async.

[addaleax]

@dariakp Mh yeah, I guess the table is a bit confusing in that the Node.js options don’t match 1:1 in behavior to the MongoDB options?

For example, we do rely on the fact that we can pass a string with the CA contents as the ca option (not tlsCAFile).