From dbee78caa418e7360013b80c2e19239f922249a0 Mon Sep 17 00:00:00 2001
From: Sam Roberts <vieuxtech@gmail.com>
Date: Mon, 21 Oct 2019 14:27:50 -0700
Subject: [PATCH] https: add client support for TLS keylog events

The keylog event is implemented on TLS sockets, but client HTTPS uses
TLS sockets managed by an agent, so accessing the underlying socket
before the TLS handshake completed was not possible.  Note that server
HTTPS already supports the keylog event because it inherits from the TLS
server.

PR-URL: https://github.com/nodejs/node/pull/30053
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
---
 doc/api/https.md                         | 25 ++++++++++++++
 lib/_http_agent.js                       | 25 +++++++++++++-
 test/parallel/test-https-agent-keylog.js | 44 ++++++++++++++++++++++++
 test/parallel/test-tls-keylog-tlsv13.js  | 10 ++++--
 4 files changed, 100 insertions(+), 4 deletions(-)
 create mode 100644 test/parallel/test-https-agent-keylog.js

diff --git a/doc/api/https.md b/doc/api/https.md
index e82ffa2225d934..a7ed44288fd3f3 100644
--- a/doc/api/https.md
+++ b/doc/api/https.md
@@ -45,6 +45,31 @@ changes:
 
     See [`Session Resumption`][] for information about TLS session reuse.
 
+#### Event: `'keylog'`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `line` {Buffer} Line of ASCII text, in NSS `SSLKEYLOGFILE` format.
+* `tlsSocket` {tls.TLSSocket} The `tls.TLSSocket` instance on which it was
+  generated.
+
+The `keylog` event is emitted when key material is generated or received by a
+connection managed by this agent (typically before handshake has completed, but
+not necessarily). This keying material can be stored for debugging, as it
+allows captured TLS traffic to be decrypted. It may be emitted multiple times
+for each socket.
+
+A typical use case is to append received lines to a common text file, which is
+later used by software (such as Wireshark) to decrypt the traffic:
+
+```js
+// ...
+https.globalAgent.on('keylog', (line, tlsSocket) => {
+  fs.appendFileSync('/tmp/ssl-keys.log', line, { mode: 0o600 });
+});
+```
+
 ## Class: `https.Server`
 <!-- YAML
 added: v0.3.4
diff --git a/lib/_http_agent.js b/lib/_http_agent.js
index 3bc2d0e6abeb1a..2f146f3b9f1171 100644
--- a/lib/_http_agent.js
+++ b/lib/_http_agent.js
@@ -27,7 +27,7 @@ const net = require('net');
 const EventEmitter = require('events');
 const debug = require('internal/util/debuglog').debuglog('http');
 const { async_id_symbol } = require('internal/async_hooks').symbols;
-
+const kOnKeylog = Symbol('onkeylog');
 // New Agent code.
 
 // The largest departure from the previous implementation is that
@@ -120,10 +120,29 @@ function Agent(options) {
       }
     }
   });
+
+  // Don't emit keylog events unless there is a listener for them.
+  this.on('newListener', maybeEnableKeylog);
 }
 Object.setPrototypeOf(Agent.prototype, EventEmitter.prototype);
 Object.setPrototypeOf(Agent, EventEmitter);
 
+function maybeEnableKeylog(eventName) {
+  if (eventName === 'keylog') {
+    this.removeListener('newListener', maybeEnableKeylog);
+    // Future sockets will listen on keylog at creation.
+    const agent = this;
+    this[kOnKeylog] = function onkeylog(keylog) {
+      agent.emit('keylog', keylog, this);
+    };
+    // Existing sockets will start listening on keylog now.
+    const sockets = Object.values(this.sockets);
+    for (let i = 0; i < sockets.length; i++) {
+      sockets[i].on('keylog', this[kOnKeylog]);
+    }
+  }
+}
+
 Agent.defaultMaxSockets = Infinity;
 
 Agent.prototype.createConnection = net.createConnection;
@@ -297,6 +316,10 @@ function installListeners(agent, s, options) {
     s.removeListener('agentRemove', onRemove);
   }
   s.on('agentRemove', onRemove);
+
+  if (agent[kOnKeylog]) {
+    s.on('keylog', agent[kOnKeylog]);
+  }
 }
 
 Agent.prototype.removeSocket = function removeSocket(s, options) {
diff --git a/test/parallel/test-https-agent-keylog.js b/test/parallel/test-https-agent-keylog.js
new file mode 100644
index 00000000000000..2fc13cbe6d8549
--- /dev/null
+++ b/test/parallel/test-https-agent-keylog.js
@@ -0,0 +1,44 @@
+'use strict';
+
+const common = require('../common');
+if (!common.hasCrypto)
+  common.skip('missing crypto');
+
+const assert = require('assert');
+const https = require('https');
+const fixtures = require('../common/fixtures');
+
+const server = https.createServer({
+  key: fixtures.readKey('agent2-key.pem'),
+  cert: fixtures.readKey('agent2-cert.pem'),
+  // Amount of keylog events depends on negotiated protocol
+  // version, so force a specific one:
+  minVersion: 'TLSv1.3',
+  maxVersion: 'TLSv1.3',
+}, (req, res) => {
+  res.end('bye');
+}).listen(() => {
+  https.get({
+    port: server.address().port,
+    rejectUnauthorized: false,
+  }, (res) => {
+    res.resume();
+    res.on('end', () => {
+      // Trigger TLS connection reuse
+      https.get({
+        port: server.address().port,
+        rejectUnauthorized: false,
+      }, (res) => {
+        server.close();
+        res.resume();
+      });
+    });
+  });
+});
+
+const verifyKeylog = (line, tlsSocket) => {
+  assert(Buffer.isBuffer(line));
+  assert.strictEqual(tlsSocket.encrypted, true);
+};
+server.on('keylog', common.mustCall(verifyKeylog, 10));
+https.globalAgent.on('keylog', common.mustCall(verifyKeylog, 10));
diff --git a/test/parallel/test-tls-keylog-tlsv13.js b/test/parallel/test-tls-keylog-tlsv13.js
index 0f6556451d013e..f26dece2f427f2 100644
--- a/test/parallel/test-tls-keylog-tlsv13.js
+++ b/test/parallel/test-tls-keylog-tlsv13.js
@@ -21,9 +21,13 @@ const server = tls.createServer({
     rejectUnauthorized: false,
   });
 
-  const verifyBuffer = (line) => assert(Buffer.isBuffer(line));
-  server.on('keylog', common.mustCall(verifyBuffer, 5));
-  client.on('keylog', common.mustCall(verifyBuffer, 5));
+  server.on('keylog', common.mustCall((line, tlsSocket) => {
+    assert(Buffer.isBuffer(line));
+    assert.strictEqual(tlsSocket.encrypted, true);
+  }, 5));
+  client.on('keylog', common.mustCall((line) => {
+    assert(Buffer.isBuffer(line));
+  }, 5));
 
   client.once('secureConnect', () => {
     server.close();