tls: cli option to enable TLS key logging to file

Debugging HTTPS or TLS connections from a Node.js app with (for example)
Wireshark is unreasonably difficult without the ability to get the TLS
key log. In theory, the application can be modified to use the
`'keylog'` event directly, but for complex apps, or apps that define
there own HTTPS Agent (like npm), this is unreasonably difficult.
Use of the option triggers a warning to be emitted so the user is
clearly notified of what is happening and its effect.
PR-URL: #30055
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: James M Snell <jasnell@gmail.com>

Author: sam-github

doc/api/cli.md

@@ -698,6 +698,15 @@ added: v4.0.0
 Specify an alternative default TLS cipher list. Requires Node.js to be built
 with crypto support (default).
 
+### `--tls-keylog=file`
+<!-- YAML
+added: REPLACEME
+-->
+
+Log TLS key material to a file. The key material is in NSS `SSLKEYLOGFILE`
+format and can be used by software (such as Wireshark) to decrypt the TLS
+traffic.
+
 ### `--tls-max-v1.2`
 <!-- YAML
 added: v12.0.0
@@ -1108,6 +1117,7 @@ Node.js options that are allowed are:
 *`--throw-deprecation`
 *`--title`
 *`--tls-cipher-list`
+*`--tls-keylog`
 *`--tls-max-v1.2`
 *`--tls-max-v1.3`
 *`--tls-min-v1.0`

doc/node.1

@@ -309,6 +309,11 @@ Specify process.title on startup.
 Specify an alternative default TLS cipher list.
 Requires Node.js to be built with crypto support. (Default)
 .
+.ItFl-tls-keylogNs=NsArfile
+Log TLS key material to a file. The key material is in NSS SSLKEYLOGFILE
+format and can be used by software (such as Wireshark) to decrypt the TLS
+traffic.
+.
 .ItFl-tls-max-v1.2
 Set default maxVersion to 'TLSv1.2'. Use to disable support for TLSv1.3.
 .

lib/_tls_wrap.js

@@ -60,6 +60,8 @@ const {
 const{ getOptionValue }=require('internal/options');
 const{ validateString }=require('internal/validators');
 consttraceTls=getOptionValue('--trace-tls');
+consttlsKeylog=getOptionValue('--tls-keylog');
+const{ appendFile }=require('fs');
 constkConnectOptions=Symbol('connect-options');
 constkDisableRenegotiation=Symbol('disable-renegotiation');
 constkErrorEmitted=Symbol('error-emitted');
@@ -560,6 +562,8 @@ TLSSocket.prototype._destroySSL = function _destroySSL() {
 };
 
 // Constructor guts, arbitrarily factored out.
+letwarnOnTlsKeylog=true;
+letwarnOnTlsKeylogError=true;
 TLSSocket.prototype._init=function(socket,wrap){
 constoptions=this._tlsOptions;
 constssl=this._handle;
@@ -643,6 +647,24 @@ TLSSocket.prototype._init = function(socket, wrap) {
 }
 }
 
+if(tlsKeylog){
+if(warnOnTlsKeylog){
+warnOnTlsKeylog=false;
+process.emitWarning('Using --tls-keylog makes TLS connections insecure '+
+'by writing secret key material to file '+tlsKeylog);
+ssl.enableKeylogCallback();
+this.on('keylog',(line)=>{
+appendFile(tlsKeylog,line,{mode: 0o600},(err)=>{
+if(err&&warnOnTlsKeylogError){
+warnOnTlsKeylogError=false;
+process.emitWarning('Failed to write TLS keylog (this warning '+
+'will not be repeated): '+err);
+}
+});
+});
+}
+}
+
 ssl.onerror=onerror;
 
 // If custom SNICallback was given, or if

src/node_options.cc

@@ -567,6 +567,10 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
 
 AddOption("--napi-modules", "", NoOp{}, kAllowedInEnvironment);
 
+AddOption("--tls-keylog",
+"log TLS decryption keys to named file for traffic analysis",
+ &EnvironmentOptions::tls_keylog, kAllowedInEnvironment);
+
 AddOption("--tls-min-v1.0",
 "set default TLS minimum to TLSv1.0 (default: TLSv1.2)",
  &EnvironmentOptions::tls_min_v1_0,

src/node_options.h

@@ -164,6 +164,7 @@ class EnvironmentOptions : public Options {
 bool tls_min_v1_3 = false;
 bool tls_max_v1_2 = false;
 bool tls_max_v1_3 = false;
+ std::string tls_keylog;
 
  std::vector<std::string> preload_modules;
 

test/parallel/test-tls-enable-keylog-cli.js

@@ -0,0 +1,57 @@
+'use strict';
+constcommon=require('../common');
+if(!common.hasCrypto)common.skip('missing crypto');
+constfixtures=require('../common/fixtures');
+
+// Test --tls-keylog CLI flag.
+
+constassert=require('assert');
+constpath=require('path');
+constfs=require('fs');
+const{ fork }=require('child_process');
+
+if(process.argv[2]==='test')
+returntest();
+
+consttmpdir=require('../common/tmpdir');
+tmpdir.refresh();
+constfile=path.resolve(tmpdir.path,'keylog.log');
+
+constchild=fork(__filename,['test'],{
+execArgv: ['--tls-keylog='+file]
+});
+
+child.on('close',common.mustCall((code,signal)=>{
+assert.strictEqual(code,0);
+assert.strictEqual(signal,null);
+constlog=fs.readFileSync(file,'utf8');
+assert(/SECRET/.test(log));
+}));
+
+functiontest(){
+const{
+ connect, keys
+}=require(fixtures.path('tls-connect'));
+
+connect({
+client: {
+checkServerIdentity: (servername,cert)=>{},
+ca: `${keys.agent1.cert}\n${keys.agent6.ca}`,
+},
+server: {
+cert: keys.agent6.cert,
+key: keys.agent6.key
+},
+},common.mustCall((err,pair,cleanup)=>{
+if(pair.server.err){
+console.trace('server',pair.server.err);
+}
+if(pair.client.err){
+console.trace('client',pair.client.err);
+}
+assert.ifError(pair.server.err);
+assert.ifError(pair.client.err);
+
+returncleanup();
+}));
+}