nodejs / nodejs/node

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

オープン
#43,994 コメント 3 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

doc stale tls
主要言語
JavaScript
スター
122k
フォーク
37.3k
平均マージ
4日 2時間
マージ済み PR(30日)
283

説明

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.

コントリビューションガイド

コントリビューションガイドを開く

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

調査の方向性

tls.TLSSocket、イベント 'secure'、およびリンク先の lib/_tls_wrap.js のセクションに関する v18 TLS ドキュメントから始めます。verifyError()tls.checkServerIdentity()getPeerCertificate() を使用する検証例と、ドキュメントに記載された API を比較します。安全な接続を確立して検証するための、サポートされていて非推奨ではない方法がドキュメントで明確に説明されているか、制限事項が明示的に記載されていれば完了です。

索引モデルが issue の本文から書いたものです。

評価

技術スタック
javascript, node.js
領域
documentation, security
issue の種類
ドキュメント
難易度
4/5
見積もり時間
3〜5日
活発さ
活発
明瞭さ
おおむね明確
初心者へのやさしさ
50/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。