nodejs / nodejs/node

How to use `new tls.TLSSocket(...)` to establish a secure connection?

Open
#43,994 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

doc stale tls
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.TLSSocket instead 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:

  1. Verify that the peer certificate is valid, see [ssl.verifyError()][].
  2. 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:

  1. The 'secure' event. In the current Node.js documentation, the only mention of 'secure' is under the deprecated tls.SecurePair, and is itself deprecated. It is also not clear that the 'secure' event is also emitted on tls.TLSSocket.
    https://nodejs.org/docs/latest-v18.x/api/tls.html#event-secure
  2. tlsSocket.ssl.verifyError(), which does not appear at all in the current documentation. Furthermore, according to https://github.com/nodejs/node/pull/840#issuecomment-74343250 tlsSocket.ssl is 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:

  1. The current documentation does not indicate that using new tls.TLSSocket(...) by itself does not result in a secure connection.
  2. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.