How to use `new tls.TLSSocket(...)` to establish a secure connection?
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 122k
- Forks
- 37.3k
- Avg merge
- 4d 2h
- Merged PRs (30d)
- 283
Description
Affected URL(s)
https://nodejs.org/docs/latest-v18.x/api/tls.html
Description of the problem
What is the correct, non-deprecated way to use the new tls.TLSSocket(...) constructor to establish a secure connection? Context: https://github.com/typelevel/fs2/security/advisories/GHSA-2cpx-6pqp-wf35
According to two unmerged docs PRs, when directly calling new tls.TLSSocket(...) it is the user's responsibility to validate peer certificates and identity.
In https://github.com/nodejs/node/pull/10846 it says:
Warning: When directly constructing a
tls.TLSSocketinstead of using
[tls.connect()][] it is the caller's responsibility to:
- manage the lifetime of the the underlying socket, including connecting it;
- validate the peer certificate and identity, see the [
'secure'][] event.
Before using the connection, the user must make the following
checks or the connection should be considered completely insecure:
- Verify that the peer certificate is valid, see [
ssl.verifyError()][].- Verify that the peer certificate is for the expected host, see
[tls.checkServerIdentity()][] and [tls.TLSSocket.getPeerCertificate()][].
In https://github.com/nodejs/node/pull/23915 it says:
It is important to remember, however,
that it is the caller's responsibility to manage the lifecycle of the provided
net.Socket, including establishing the connection and validating peer
certificates and identity. See the ['secure'][] event.
And includes an example:
tlsSocket.on('secure', function() {
const err = this.verifyError() ||
tls.checkServerIdentity(hostname, this.getPeerCertificate());
if (err)
this.destroy(err);
});
Both PRs demonstrate how to do this validation, but require use of:
- The
'secure'event. In the current Node.js documentation, the only mention of'secure'is under the deprecatedtls.SecurePair, and is itself deprecated. It is also not clear that the'secure'event is also emitted ontls.TLSSocket.
https://nodejs.org/docs/latest-v18.x/api/tls.html#event-secure tlsSocket.ssl.verifyError(), which does not appear at all in the current documentation. Furthermore, according to https://github.com/nodejs/node/pull/840#issuecomment-74343250tlsSocket.sslis a "legacy property".
Note that the described validation steps appear to be consistent with internal use
https://github.com/nodejs/node/blob/5fbf33ef8641cf57bfbb7f0c87f83447c44266b8/lib/_tls_wrap.js#L1106
https://github.com/nodejs/node/blob/5fbf33ef8641cf57bfbb7f0c87f83447c44266b8/lib/_tls_wrap.js#L1044-L1055
This leaves me with two concerns:
- The current documentation does not indicate that using
new tls.TLSSocket(...)by itself does not result in a secure connection. - As far as I can tell it is impossible to use
new tls.TLSSocket(...)to establish a secure connection without relying on APIs that are undocumented, deprecated, and/or legacy.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the v18 TLS documentation for tls.TLSSocket, the 'secure' event, and the linked lib/_tls_wrap.js sections. Compare the documented APIs with the validation example using verifyError(), tls.checkServerIdentity(), and getPeerCertificate(). Done means the docs clearly explain a supported, non-deprecated way to establish and validate a secure connection, or explicitly document the limitation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, node.js
- Domain
- documentation, security
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 50/100