tls,cli: add --trace-tls command-line flag

This commit adds a --trace-tls command-line flag. The
purpose is to enable tracing of TLS connections without the
need to modify existing application code.
PR-URL: #27497
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>

Author: cjihrig

doc/api/cli.md

@@ -632,6 +632,14 @@ added: v2.1.0
 Prints a stack trace whenever synchronous I/O is detected after the first turn
 of the event loop.
 
+### `--trace-tls`
+<!-- YAML
+added: REPLACEME
+-->
+
+Prints TLS packet trace information to `stderr`. This can be used to debug TLS
+connection problems.
+
 ### `--trace-warnings`
 <!-- YAML
 added: v6.0.0
@@ -889,6 +897,7 @@ Node.js options that are allowed are:
 -`--trace-event-file-pattern`
 -`--trace-events-enabled`
 -`--trace-sync-io`
+-`--trace-tls`
 -`--trace-warnings`
 -`--track-heap-objects`
 -`--unhandled-rejections`

doc/node.1

@@ -302,6 +302,9 @@ Enable the collection of trace event tracing information.
 .ItFl-trace-sync-io
 Print a stack trace whenever synchronous I/O is detected after the first turn of the event loop.
 .
+.ItFl-trace-tls
+Prints TLS packet trace information to stderr.
+.
 .ItFl-trace-warnings
 Print stack traces for process warnings (including deprecations).
 .

lib/_tls_wrap.js

@@ -56,7 +56,9 @@ const {
 ERR_TLS_SESSION_ATTACK,
 ERR_TLS_SNI_FROM_SERVER
 }=require('internal/errors').codes;
+const{ getOptionValue }=require('internal/options');
 const{ validateString }=require('internal/validators');
+consttraceTls=getOptionValue('--trace-tls');
 constkConnectOptions=Symbol('connect-options');
 constkDisableRenegotiation=Symbol('disable-renegotiation');
 constkErrorEmitted=Symbol('error-emitted');
@@ -68,6 +70,7 @@ const kEnableTrace = Symbol('enableTrace');
 constnoop=()=>{};
 
 letipServernameWarned=false;
+lettlsTracingWarned=false;
 
 // Server side times how long a handshake is taking to protect against slow
 // handshakes being used for DoS.
@@ -343,9 +346,17 @@ function initRead(tlsSocket, socket) {
 
 functionTLSSocket(socket,opts){
 consttlsOptions={ ...opts};
-constenableTrace=tlsOptions.enableTrace;
+letenableTrace=tlsOptions.enableTrace;
 
-if(typeofenableTrace!=='boolean'&&enableTrace!=null){
+if(enableTrace==null){
+enableTrace=traceTls;
+
+if(enableTrace&&!tlsTracingWarned){
+tlsTracingWarned=true;
+process.emitWarning('Enabling --trace-tls can expose sensitive data in '+
+'the resulting log.');
+}
+}elseif(typeofenableTrace!=='boolean'){
 thrownewERR_INVALID_ARG_TYPE(
 'options.enableTrace','boolean',enableTrace);
 }

src/node_options.cc

@@ -373,6 +373,10 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
 "first tick",
  &EnvironmentOptions::trace_sync_io,
 kAllowedInEnvironment);
+AddOption("--trace-tls",
+"prints TLS packet trace information to stderr",
+ &EnvironmentOptions::trace_tls,
+kAllowedInEnvironment);
 AddOption("--trace-warnings",
 "show stack traces on process warnings",
  &EnvironmentOptions::trace_warnings,

src/node_options.h

@@ -118,6 +118,7 @@ class EnvironmentOptions : public Options {
 bool throw_deprecation = false;
 bool trace_deprecation = false;
 bool trace_sync_io = false;
+bool trace_tls = false;
 bool trace_warnings = false;
  std::string unhandled_rejections;
  std::string userland_loader;

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

@@ -0,0 +1,59 @@
+// Flags: --expose-internals
+'use strict';
+constcommon=require('../common');
+if(!common.hasCrypto)common.skip('missing crypto');
+constfixtures=require('../common/fixtures');
+
+// Test --trace-tls CLI flag.
+
+constassert=require('assert');
+const{ fork }=require('child_process');
+
+if(process.argv[2]==='test')
+returntest();
+
+constbinding=require('internal/test/binding').internalBinding;
+
+if(!binding('tls_wrap').HAVE_SSL_TRACE)
+returncommon.skip('no SSL_trace() compiled into openssl');
+
+constchild=fork(__filename,['test'],{
+silent: true,
+execArgv: ['--trace-tls']
+});
+
+letstderr='';
+child.stderr.setEncoding('utf8');
+child.stderr.on('data',(data)=>stderr+=data);
+child.on('close',common.mustCall(()=>{
+assert(/Warning:Enabling--trace-tlscanexposesensitive/.test(stderr));
+assert(/ReceivedRecord/.test(stderr));
+assert(/ClientHello/.test(stderr));
+}));
+
+// For debugging and observation of actual trace output.
+child.stderr.pipe(process.stderr);
+child.stdout.pipe(process.stdout);
+
+child.on('exit',common.mustCall((code)=>{
+assert.strictEqual(code,0);
+}));
+
+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)=>{
+returncleanup();
+}));
+}