src: suggest --use-system-ca when a certificate error occurs

PR-URL: #57362
Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

Author: Aditi-1400

doc/api/tls.md

@@ -547,6 +547,12 @@ description are taken from deps/openssl/openssl/crypto/x509/x509_txt.c
 *`'CERT_REJECTED'`: Certificate rejected.
 *`'HOSTNAME_MISMATCH'`: Hostname mismatch.
 
+When certificate errors like `UNABLE_TO_VERIFY_LEAF_SIGNATURE`,
+`DEPTH_ZERO_SELF_SIGNED_CERT`, or `UNABLE_TO_GET_ISSUER_CERT` occur, Node.js
+appends a hint suggesting that if the root CA is installed locally,
+try running with the `--use-system-ca` flag to direct developers towards a
+secure solution, to prevent unsafe workarounds.
+
 ## Class: `tls.CryptoStream`
 
 <!-- YAML

src/crypto/crypto_common.cc

@@ -53,8 +53,20 @@ SSLSessionPointer GetTLSSession(const unsigned char* buf, size_t length) {
 }
 
 MaybeLocal<Value> GetValidationErrorReason(Environment* env, int err) {
-auto reason = X509Pointer::ErrorReason(err).value_or("");
+auto reason = std::string(X509Pointer::ErrorReason(err).value_or(""));
 if (reason == "") returnUndefined(env->isolate());
+
+// Suggest --use-system-ca if the error indicates a certificate issue
+bool suggest_system_ca =
+ (err == X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE) ||
+ (err == X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT) ||
+ ((err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT) &&
+ !per_process::cli_options->use_system_ca);
+
+if (suggest_system_ca) {
+ reason.append("; if the root CA is installed locally, "
+"try running Node.js with --use-system-ca");
+ }
 returnOneByteString(env->isolate(), reason);
 }
 

test/parallel/test-https-agent-create-connection.js

@@ -17,7 +17,7 @@ const options = {
 
 constexpectedHeader=/^HTTP\/1\.1200OK/;
 constexpectedBody=/helloworld\n/;
-constexpectCertError=/^Error:unabletoverifythefirstcertificate$/;
+constexpectCertError=/^UNABLE_TO_VERIFY_LEAF_SIGNATURE$/;
 
 constcheckRequest=(socket,server)=>{
 letresult='';
@@ -112,7 +112,7 @@ function createServer() {
 constoptions=null;
 constsocket=agent.createConnection(port,host,options);
 socket.on('error',common.mustCall((e)=>{
-assert.match(e.toString(),expectCertError);
+assert.match(e.code,expectCertError);
 server.close();
 }));
 }));
@@ -127,7 +127,7 @@ function createServer() {
 constoptions=undefined;
 constsocket=agent.createConnection(port,host,options);
 socket.on('error',common.mustCall((e)=>{
-assert.match(e.toString(),expectCertError);
+assert.match(e.code,expectCertError);
 server.close();
 }));
 }));

test/parallel/test-tls-addca.js

@@ -34,7 +34,7 @@ connect({
 server: serverOptions,
 },common.mustCall((err,pair,cleanup)=>{
 assert(err);
-assert.strictEqual(err.message,'unable to verify the first certificate');
+assert.strictEqual(err.code,'UNABLE_TO_VERIFY_LEAF_SIGNATURE');
 cleanup();
 
 // This time it should connect because contextWithCert includes the needed CA

test/parallel/test-tls-friendly-error-message.js

@@ -40,6 +40,5 @@ tls.createServer({ key, cert }).on('connection', common.mustCall(function() {
 constoptions={port: this.address().port,rejectUnauthorized: true};
 tls.connect(options).on('error',common.mustCall(function(err){
 assert.strictEqual(err.code,'UNABLE_TO_VERIFY_LEAF_SIGNATURE');
-assert.strictEqual(err.message,'unable to verify the first certificate');
 }));
 }));

test/parallel/test-tls-set-secure-context.js

@@ -13,7 +13,6 @@ const assert = require('assert');
 constevents=require('events');
 consthttps=require('https');
 consttimers=require('timers/promises');
-const{ hasOpenSSL3 }=require('../common/crypto');
 constfixtures=require('../common/fixtures');
 constcredentialOptions=[
 {
@@ -57,17 +56,18 @@ server.listen(0, common.mustCall(() => {
 
 server.setSecureContext(credentialOptions[1]);
 firstResponse.write('request-');
-consterrorMessageRegex=hasOpenSSL3 ?
-/^Error:self-signedcertificate$/ :
-/^Error:selfsignedcertificate$/;
-awaitassert.rejects(makeRequest(port,3),errorMessageRegex);
+awaitassert.rejects(makeRequest(port,3),{
+code: 'DEPTH_ZERO_SELF_SIGNED_CERT',
+});
 
 server.setSecureContext(credentialOptions[0]);
 assert.strictEqual(awaitmakeRequest(port,4),'success');
 
 server.setSecureContext(credentialOptions[1]);
 firstResponse.end('fun!');
-awaitassert.rejects(makeRequest(port,5),errorMessageRegex);
+awaitassert.rejects(makeRequest(port,5),{
+code: 'DEPTH_ZERO_SELF_SIGNED_CERT',
+});
 
 assert.strictEqual(awaitfirstRequest,'multi-request-success-fun!');
 server.close();

test/parallel/test-tls-socket-default-options.js

@@ -10,11 +10,11 @@ const {
 }=require(fixtures.path('tls-connect'));
 
 test(undefined,(err)=>{
-assert.strictEqual(err.message,'unable to verify the first certificate');
+assert.strictEqual(err.code,'UNABLE_TO_VERIFY_LEAF_SIGNATURE');
 });
 
 test({},(err)=>{
-assert.strictEqual(err.message,'unable to verify the first certificate');
+assert.strictEqual(err.code,'UNABLE_TO_VERIFY_LEAF_SIGNATURE');
 });
 
 test(
@@ -30,8 +30,8 @@ test(
 test(
 {secureContext: tls.createSecureContext(),ca: keys.agent1.ca},
 (err)=>{
-assert.strictEqual(err.message,
-'unable to verify the first certificate');
+assert.strictEqual(err.code,
+'UNABLE_TO_VERIFY_LEAF_SIGNATURE');
 });
 
 functiontest(client,callback){
@@ -42,7 +42,7 @@ function test(client, callback) {
 cert: keys.agent1.cert,
 },
 },function(err,pair,cleanup){
-assert.strictEqual(err.message,'unable to verify the first certificate');
+assert.strictEqual(err.code,'UNABLE_TO_VERIFY_LEAF_SIGNATURE');
 letrecv='';
 pair.server.server.once('secureConnection',common.mustCall((conn)=>{
 conn.on('data',(data)=>recv+=data);