doc, tls: deprecate createSecurePair

[jhamhader]

Pull Request check-list

Please make sure to review and check all of these items:

• Does make -j8 test (UNIX) or vcbuild test nosign (Windows) pass with
  this change (including linting)?
• Is the commit message formatted according to CONTRIBUTING.md?
• If this change fixes a bug (or a performance problem), is a regression
  test (or a benchmark) included?
• Is a documentation update included (if this change modifies
  existing APIs, or introduces new ones)?

NOTE: these things are not required to open a PR and can be done
afterwards / while the PR is open.

Affected core subsystem(s)

Please provide affected core subsystem(s) (like buffer, cluster, crypto, etc)

Description of change

createSecurePair uses tls_legacy and the legacy Connection from
node_crypto.cc. Deprecate them in favor of TLSSocket.

See #5924

[benjamingr]

I think we should start providing examples of how to use different things when posting deprecations but I'm not saying this PR is where we should start.

The contents of the PR are fine but this sort of thing needs to be discussed by the CTC in a meeting.

[jasnell]

/cc @nodejs/ctc @nodejs/crypto

[indutny]

I agree with @benjamingr.

[jasnell]

I agree that an example showing how the alternative TLSSocket would be used.

[ChALkeR]

grep in npm modules: https://gist.github.com/ChALkeR/c695d55a9a2b30d9481291829e1e0f58

[jasnell]

@nodejs/ctc discussed this today and had no objections. If there are no objections by Monday I will land before v6 is cut. There may need to be additional edits to this PR before then

[jhamhader]

@jasnell - sure. What is missing?

[indutny]

Suggestion of how createSecurePair() could be replaced by modern APIs :)

[jasnell]

Yeah, nothing specific and nothing critical, but an example would be helpful.

[jhamhader]

On it

[indutny]

Yay! @jhamhader you rock!

[jhamhader]

Updated (tried to keep it short)

[indutny]

Not sure about markdown formatting in docs, but text SGTM

[jasnell]

style nit, can you add the js to the end of the three backticks and put a blank line before the examples

[jasnell]

Added a nit that I can fix on landing. LGTM

[jasnell]

Landed in 31de5cc

[arthurschreiber]

Hey @jasnell and @indutny,

I'm the maintainer of a npm package called tedious, which is a database driver for Microsofts SQLServer. We have been using ´tls.createSecurePair´ to implement tls connection handling as specified by MS-TDS, Microsofts specification of the TDS protocol.

One peculiarity of this protocol was the way the TLS connection is established - the TLS data for the handshake needs to be wrapped inside TDS protocol packets. With ´tls.createSecurePair´, this was easily possible. I looked into switching to tls.connect instead, but I did not find any way how to implement this without the deprecated API.

The existing code can be found here:
https://github.com/pekim/tedious/blob/master/src/message-io.js (in the startTls method).

Could you please take a look and let me know how something similar could be achieved with the new API? I did not find anything in the documentation. Thanks!

[bnoordhuis]

@nodejs/crypto I think we should undo the deprecation. I was under the impression that CleartextStream and EncryptedStream were exported, letting you cobble a SecurePair together, but they're not.

The use case of streaming TLS cipher/decipher not tied to a socket doesn't seem to be supported by non-deprecated APIs at the moment.

[indutny]

@bnoordhuis it is supported, actually. A regular stream.Duplex instance may be passed to TLSSocket as a socket option.

[bnoordhuis]

That isn't very obvious. I did notice we have a few tests that pass in a Duplex instance but the documentation says that socket should be "an instance of net.Socket" and that it constructs "a new tls.TLSSocket object from an existing TCP socket."

[indutny]

Yeah, docs lack clarity, but this is certainly possible.