tls: expose detailed certificate validation failure reasons in access logs (envoyproxy#42420)

Propagate detailed certificate validation errors (e.g., "certificate has
expired", "unable to get local issuer certificate", "SAN matcher
failed") from DefaultCertValidator through SslExtendedSocketInfo to the
transport failure reason string in access logs.

Previously, when TLS certificate validation failed, access logs only
showed the generic CERTIFICATE_VERIFY_FAILED error without actionable
details. This made debugging TLS issues difficult in production where
debug logging is not feasible. 

The detailed error is now visible in %UPSTREAM_TRANSPORT_FAILURE_REASON%
and %DOWNSTREAM_TRANSPORT_FAILURE_REASON% access log formatters.

Fixes envoyproxy#42266

Signed-off-by: Prashanth Josyula <prashanth.chaitanya@salesforce.com>

Author: prashanthjos

changelogs/current.yaml

@@ -424,6 +424,14 @@ new_features:
 - area: tls_inspector
   change: |
     Added configuration parameter to TLS inspector for maximum acceptable client hello size.
+- area: tls
+  change: |
+    Enhanced TLS certificate validation failure messages in access logs to include detailed error information.
+    The ``%DOWNSTREAM_TRANSPORT_FAILURE_REASON%`` and ``%UPSTREAM_TRANSPORT_FAILURE_REASON%`` access log
+    formatters now include specific validation failure reasons such as ``verify cert failed: SAN matcher``,
+    ``verify cert failed: cert hash and spki``, or the OpenSSL verification error string (e.g., certificate
+    has expired, unable to get local issuer certificate). This provides better visibility into TLS handshake
+    failures without requiring debug-level logging.
 - area: ext_proc
   change: |
     Added support for forwarding cluster metadata to ext_proc server.

envoy/ssl/ssl_socket_extended_info.h

@@ -9,6 +9,8 @@
 #include "envoy/event/dispatcher.h"
 #include "envoy/ssl/handshaker.h"
 
+#include "absl/strings/string_view.h"
+
 namespace Envoy {
 namespace Ssl {
 
@@ -112,6 +114,17 @@ class SslExtendedSocketInfo {
    * @return CertificateSelectionStatus the cert selection status.
    */
   virtual CertificateSelectionStatus certificateSelectionResult() const PURE;
+
+  /**
+   * Set detailed certificate validation error information.
+   * @param error_details the detailed error message from certificate validation.
+   */
+  virtual void setCertificateValidationError(absl::string_view error_details) PURE;
+
+  /**
+   * @return the detailed certificate validation error message, or empty if none.
+   */
+  virtual absl::string_view certificateValidationError() const PURE;
 };
 
 } // namespace Ssl

source/common/tls/context_impl.cc

@@ -487,6 +487,10 @@ enum ssl_verify_result_t ContextImpl::customVerifyCallback(SSL* ssl, uint8_t* ou
     if (result.tls_alert.has_value() && out_alert) {
       *out_alert = result.tls_alert.value();
     }
+    // Store detailed error information for access log reporting.
+    if (result.error_details.has_value()) {
+      extended_socket_info->setCertificateValidationError(result.error_details.value());
+    }
     return ssl_verify_invalid;
   }
   }

source/common/tls/ssl_handshaker.cc

@@ -20,13 +20,16 @@ void ValidateResultCallbackImpl::onSslHandshakeCancelled() { extended_socket_inf
 
 void ValidateResultCallbackImpl::onCertValidationResult(bool succeeded,
                                                         Ssl::ClientValidationStatus detailed_status,
-                                                        const std::string& /*error_details*/,
+                                                        const std::string& error_details,
                                                         uint8_t tls_alert) {
   if (!extended_socket_info_.has_value()) {
     return;
   }
   extended_socket_info_->setCertificateValidationStatus(detailed_status);
   extended_socket_info_->setCertificateValidationAlert(tls_alert);
+  if (!error_details.empty()) {
+    extended_socket_info_->setCertificateValidationError(error_details);
+  }
   extended_socket_info_->onCertificateValidationCompleted(succeeded, true);
 }
 

source/common/tls/ssl_handshaker.h

@@ -93,6 +93,11 @@ class SslExtendedSocketInfoImpl : public Envoy::Ssl::SslExtendedSocketInfo {
     return cert_selection_result_;
   }
 
+  void setCertificateValidationError(absl::string_view error_details) override {
+    cert_validation_error_ = std::string(error_details);
+  }
+  absl::string_view certificateValidationError() const override { return cert_validation_error_; }
+
 private:
   Envoy::Ssl::ClientValidationStatus certificate_validation_status_{
       Envoy::Ssl::ClientValidationStatus::NotValidated};
@@ -112,6 +117,8 @@ class SslExtendedSocketInfoImpl : public Envoy::Ssl::SslExtendedSocketInfo {
   // NotStarted if no cert selection has ever been kicked off.
   Ssl::CertificateSelectionStatus cert_selection_result_{
       Ssl::CertificateSelectionStatus::NotStarted};
+  // Stores the detailed certificate validation error message.
+  std::string cert_validation_error_;
 };
 
 class SslHandshakerImpl : public ConnectionInfoImplBase,

source/common/tls/ssl_socket.cc

@@ -211,13 +211,17 @@ PostIoAction SslSocket::doHandshake() { return info_->doHandshake(); }
 void SslSocket::drainErrorQueue() {
   bool saw_error = false;
   bool saw_counted_error = false;
+  bool saw_cert_verify_failed = false;
+  bool saw_no_client_cert = false;
   while (uint64_t err = ERR_get_error()) {
     if (ERR_GET_LIB(err) == ERR_LIB_SSL) {
       if (ERR_GET_REASON(err) == SSL_R_PEER_DID_NOT_RETURN_A_CERTIFICATE) {
         ctx_->stats().fail_verify_no_cert_.inc();
         saw_counted_error = true;
+        saw_no_client_cert = true;
       } else if (ERR_GET_REASON(err) == SSL_R_CERTIFICATE_VERIFY_FAILED) {
         saw_counted_error = true;
+        saw_cert_verify_failed = true;
       }
     } else if (ERR_GET_LIB(err) == ERR_LIB_SYS) {
       // Any syscall errors that result in connection closure are already tracked in other
@@ -241,6 +245,23 @@ void SslSocket::drainErrorQueue() {
     return;
   }
 
+  // Append detailed error info for certificate-related failures.
+  bool added_detail = false;
+  if (saw_cert_verify_failed) {
+    auto* extended_socket_info = reinterpret_cast<Envoy::Ssl::SslExtendedSocketInfo*>(
+        SSL_get_ex_data(rawSsl(), ContextImpl::sslExtendedSocketInfoIndex()));
+    if (extended_socket_info != nullptr) {
+      absl::string_view cert_validation_error = extended_socket_info->certificateValidationError();
+      if (!cert_validation_error.empty()) {
+        absl::StrAppend(&failure_reason_, ":", cert_validation_error);
+        added_detail = true;
+      }
+    }
+  }
+  if (!added_detail && saw_no_client_cert) {
+    absl::StrAppend(&failure_reason_, ":peer did not provide required client certificate");
+  }
+
   if (!failure_reason_.empty()) {
     absl::StrAppend(&failure_reason_, ":TLS_error_end");
     ENVOY_CONN_LOG(debug, "remote address:{},{}", callbacks_->connection(),

test/common/tls/cert_validator/default_validator_test.cc

@@ -817,6 +817,79 @@ TEST(DefaultCertValidatorTest, DefaultValidatorCaExpirationStats) {
   EXPECT_EQ(gauge_opt->get().value(), std::chrono::seconds::max().count());
 }
 
+// Test that ValidationResults contains detailed error information when SAN validation fails.
+TEST(DefaultCertValidatorTest, TestCertificateValidationErrorDetailsForSanFailure) {
+  NiceMock<Server::Configuration::MockServerFactoryContext> context;
+  Stats::TestUtil::TestStore test_store;
+  SslStats stats = generateSslStats(*test_store.rootScope());
+
+  // Load a certificate with DNS SANs
+  bssl::UniquePtr<X509> cert = readCertFromFile(
+      TestEnvironment::substitute("{{ test_rundir }}/test/common/tls/test_data/san_dns_cert.pem"));
+
+  // Create SAN matchers that won't match the certificate (using regex as DNS requires it)
+  envoy::type::matcher::v3::StringMatcher matcher;
+  matcher.MergeFrom(TestUtility::createRegexMatcher(R"raw(nomatch\.example\.com)raw"));
+  std::vector<SanMatcherPtr> subject_alt_name_matchers;
+  subject_alt_name_matchers.push_back(
+      SanMatcherPtr{std::make_unique<StringSanMatcher>(GEN_DNS, matcher, context)});
+
+  // Create the validator with no config (so verify_trusted_ca_ is false)
+  auto default_validator =
+      std::make_unique<Extensions::TransportSockets::Tls::DefaultCertValidator>(
+          /*CertificateValidationContextConfig=*/nullptr, stats, context);
+
+  // Call verifyCertificate directly which populates error_details on SAN mismatch
+  std::string error_details;
+  uint8_t tls_alert;
+  Ssl::ClientValidationStatus status = default_validator->verifyCertificate(
+      cert.get(), /*verify_san_list=*/{}, subject_alt_name_matchers, /*stream_info=*/{},
+      &error_details, &tls_alert);
+
+  // Validation should fail because the SAN doesn't match
+  EXPECT_EQ(Ssl::ClientValidationStatus::Failed, status);
+
+  // The error_details should be populated with a meaningful error message
+  EXPECT_EQ(error_details, "verify cert failed: SAN matcher");
+}
+
+// Test that TestSslExtendedSocketInfo properly stores and retrieves certificate validation errors.
+TEST(DefaultCertValidatorTest, TestSslExtendedSocketInfoCertValidationError) {
+  TestSslExtendedSocketInfo extended_socket_info;
+
+  // Initially the error should be empty
+  EXPECT_TRUE(extended_socket_info.certificateValidationError().empty());
+
+  // Set an error
+  const std::string error_msg = "verify cert failed: X509_verify_cert: certificate has expired";
+  extended_socket_info.setCertificateValidationError(error_msg);
+
+  // Verify the error is stored and retrievable
+  EXPECT_EQ(error_msg, extended_socket_info.certificateValidationError());
+}
+
+// Test that empty cert chain returns appropriate error details.
+TEST(DefaultCertValidatorTest, TestEmptyCertChainErrorDetails) {
+  NiceMock<Server::Configuration::MockServerFactoryContext> context;
+  Stats::TestUtil::TestStore test_store;
+  SslStats stats = generateSslStats(*test_store.rootScope());
+
+  auto default_validator =
+      std::make_unique<Extensions::TransportSockets::Tls::DefaultCertValidator>(
+          /*CertificateValidationContextConfig=*/nullptr, stats, context);
+
+  SSLContextPtr ssl_ctx = SSL_CTX_new(TLS_method());
+  bssl::UniquePtr<STACK_OF(X509)> cert_chain(sk_X509_new_null());
+
+  ValidationResults results = default_validator->doVerifyCertChain(
+      *cert_chain, /*callback=*/nullptr,
+      /*transport_socket_options=*/nullptr, *ssl_ctx, {}, false, "");
+
+  EXPECT_EQ(ValidationResults::ValidationStatus::Failed, results.status);
+  EXPECT_TRUE(results.error_details.has_value());
+  EXPECT_EQ(results.error_details.value(), "verify cert failed: empty cert chain");
+}
+
 } // namespace Tls
 } // namespace TransportSockets
 } // namespace Extensions

test/common/tls/cert_validator/test_common.h

@@ -47,11 +47,17 @@ class TestSslExtendedSocketInfo : public Envoy::Ssl::SslExtendedSocketInfo {
     return cert_selection_result_;
   }
 
+  void setCertificateValidationError(absl::string_view error_details) override {
+    cert_validation_error_ = std::string(error_details);
+  }
+  absl::string_view certificateValidationError() const override { return cert_validation_error_; }
+
 private:
   Envoy::Ssl::ClientValidationStatus status_;
   Ssl::ValidateStatus validate_result_{Ssl::ValidateStatus::NotStarted};
   Ssl::CertificateSelectionStatus cert_selection_result_{
       Ssl::CertificateSelectionStatus::NotStarted};
+  std::string cert_validation_error_;
 };
 
 class TestCertificateValidationContextConfig

test/common/tls/handshaker_test.cc

@@ -244,6 +244,71 @@ TEST_F(HandshakerTest, NormalOperationWithSslHandshakerImplForTest) {
   EXPECT_EQ(post_io_action, Network::PostIoAction::Close);
 }
 
+// Test that SslExtendedSocketInfoImpl properly stores and retrieves certificate validation errors.
+TEST_F(HandshakerTest, SslExtendedSocketInfoCertValidationError) {
+  NiceMock<Network::MockConnection> mock_connection;
+  ON_CALL(mock_connection, state).WillByDefault(Return(Network::Connection::State::Closed));
+
+  NiceMock<MockHandshakeCallbacks> handshake_callbacks;
+  ON_CALL(handshake_callbacks, connection()).WillByDefault(ReturnRef(mock_connection));
+
+  SslHandshakerImpl handshaker(std::move(server_ssl_), 0, &handshake_callbacks);
+
+  // Get the extended socket info through the SSL ex_data mechanism
+  auto* extended_info =
+      reinterpret_cast<Ssl::SslExtendedSocketInfo*>(SSL_get_ex_data(handshaker.ssl(), 0));
+  ASSERT_NE(extended_info, nullptr);
+
+  // Initially, the certificate validation error should be empty.
+  EXPECT_TRUE(extended_info->certificateValidationError().empty());
+
+  // Set the certificate validation error.
+  const std::string error_msg =
+      "verify cert failed: X509_verify_cert: certificate verification error at depth 0: "
+      "certificate has expired";
+  extended_info->setCertificateValidationError(error_msg);
+
+  // Verify the error is properly stored and retrievable.
+  EXPECT_EQ(error_msg, extended_info->certificateValidationError());
+
+  // Test that we can overwrite the error.
+  const std::string new_error_msg = "verify cert failed: SAN matcher";
+  extended_info->setCertificateValidationError(new_error_msg);
+  EXPECT_EQ(new_error_msg, extended_info->certificateValidationError());
+}
+
+// Test that ValidateResultCallbackImpl properly stores error details.
+TEST_F(HandshakerTest, ValidateResultCallbackStoresErrorDetails) {
+  NiceMock<Network::MockConnection> mock_connection;
+  ON_CALL(mock_connection, state).WillByDefault(Return(Network::Connection::State::Open));
+
+  NiceMock<MockHandshakeCallbacks> handshake_callbacks;
+  ON_CALL(handshake_callbacks, connection()).WillByDefault(ReturnRef(mock_connection));
+
+  SslHandshakerImpl handshaker(std::move(server_ssl_), 0, &handshake_callbacks);
+
+  // Get the extended socket info
+  auto* extended_info =
+      reinterpret_cast<Ssl::SslExtendedSocketInfo*>(SSL_get_ex_data(handshaker.ssl(), 0));
+  ASSERT_NE(extended_info, nullptr);
+
+  // Create a validation callback (simulating async validation)
+  auto callback = extended_info->createValidateResultCallback();
+  ASSERT_NE(callback, nullptr);
+
+  // Simulate validation failure with error details
+  const std::string error_details =
+      "verify cert failed: X509_verify_cert: certificate verification error at depth 1: "
+      "unable to get local issuer certificate";
+  callback->onCertValidationResult(false, Ssl::ClientValidationStatus::Failed, error_details,
+                                   SSL_AD_UNKNOWN_CA);
+
+  // Verify the error was stored in extended socket info
+  EXPECT_EQ(error_details, extended_info->certificateValidationError());
+  EXPECT_EQ(Ssl::ClientValidationStatus::Failed, extended_info->certificateValidationStatus());
+  EXPECT_EQ(SSL_AD_UNKNOWN_CA, extended_info->certificateValidationAlert());
+}
+
 } // namespace
 } // namespace Tls
 } // namespace TransportSockets

test/extensions/access_loggers/grpc/tcp_grpc_access_log_integration_test.cc

@@ -833,7 +833,7 @@ TEST_P(TcpGrpcAccessLogIntegrationTest, TlsHandshakeFailure_VerifyFailed) {
       downstream_local_address:
         socket_address:
           address: {0}
-      downstream_transport_failure_reason: "TLS_error:|268435581:SSL routines:OPENSSL_internal:CERTIFICATE_VERIFY_FAILED:TLS_error_end"
+      downstream_transport_failure_reason: "TLS_error:|268435581:SSL routines:OPENSSL_internal:CERTIFICATE_VERIFY_FAILED:verify cert failed: cert hash and spki:TLS_error_end"
       access_log_type: NotSet
       downstream_direct_remote_address:
         socket_address: