Add verifyContext to CertificateIdentityVerifier

Alex Snast · meta-codesync[bot] · commit 3414577be075 · 2025-11-25T00:57:44.000-08:00
Summary:
This diff adds a new `verifyContext()` method to the `CertificateIdentityVerifier` interface that is called during OpenSSL's certificate verification callback for each certificate in the chain. This allows implementers to inspect and verify the entire certificate chain by accessing the `X509_STORE_CTX` directly.

**Key Changes:**
- Added virtual `verifyContext(bool preverifyOk, X509_STORE_CTX&amp; ctx)` method to `CertificateIdentityVerifier` with a default pass-through implementation
- `verifyContext()` is called **for each certificate in the chain** (root → intermediate(s) → leaf) during the SSL handshake
- Modified `AsyncSSLSocket::sslVerifyCallback()` to call `verifyContext()` after `handshakeVer()` and before `verifyLeaf()`
- `verifyContext()` updates the verification state without short-circuiting - unlike `handshakeVer()`, it allows processing to continue even when changing the result
- If `verifyContext()` returns `false`, verification fails and `verifyLeaf()` will NOT be called
- If `verifyContext()` returns `true`, verification succeeds and `verifyLeaf()` may be called for the leaf certificate at depth 0
- Updated `MockCertificateIdentityVerifier` to include `MOCK_METHOD` for the new method
- Updated existing tests to mock `verifyContext()` calls and verify proper call ordering
- Comprehensively updated documentation to accurately describe the verification flow and `verifyContext()` behavior

**Why This Change:**
This provides more flexibility for custom certificate verification by allowing access to the full certificate chain context. Some verification scenarios require:
- Inspecting the entire chain (not just the leaf certificate)
- Accessing OpenSSL's `X509_STORE_CTX` for advanced validation
- Performing verification at different chain depths
- Overriding OpenSSL's verification decisions (can rescue failed OpenSSL verifications or fail successful ones)
- Short-circuiting verification early based on chain-level policies

The method is marked `noexcept` and allows the verification flow to continue, enabling `verifyLeaf()` to be called for additional leaf certificate validation even when `verifyContext()` changes the result.

**Verification Flow:**
1. OpenSSL performs internal certificate chain validation
2. HandshakeCB's `handshakeVer()` is invoked (if registered)
   - Short-circuits if it changes the result
3. CertificateIdentityVerifier's `verifyContext()` is invoked (if registered)
   - Called once for each cert in chain
   - Updates verification state without short-circuiting
   - Can override OpenSSL's decision in either direction
4. CertificateIdentityVerifier's `verifyLeaf()` is invoked (if registered)
   - Called only for leaf certificate at depth 0
   - Only if all previous steps succeeded (preverifyOk is true)

Reviewed By: yfeldblum

Differential Revision: D87812821

fbshipit-source-id: a1ba21bb643c497c9da67f6e7deda75a05d8da0c
diff --git a/third-party/folly/src/folly/io/async/AsyncSSLSocket.cpp b/third-party/folly/src/folly/io/async/AsyncSSLSocket.cpp
@@ -1996,24 +1996,36 @@ int AsyncSSLSocket::sslVerifyCallback(
 
   if (self->handshakeCallback_) {
     int callbackOk =
-        (self->handshakeCallback_->handshakeVer(self, preverifyOk, x509Ctx))
+        self->handshakeCallback_->handshakeVer(self, preverifyOk, x509Ctx)
         ? 1
         : 0;
 
     if (preverifyOk != callbackOk) {
       // HandshakeCB overwrites result from OpenSSL. One way or another, do not
-      // call CertificateIdentityVerifier.
+      // call verifyLeaf.
       return callbackOk;
     }
   }
 
+  // verifyContext can override the OpenSSL verification result. Unlike
+  // handshakeVer, it doesn't return early - allowing verifyLeaf to be called
+  // for the leaf certificate even if verifyContext changes the result.
+  if (self->certificateIdentityVerifier_) {
+    preverifyOk =
+        self->certificateIdentityVerifier_->verifyContext(preverifyOk, *x509Ctx)
+        ? 1
+        : 0;
+  }
+
   if (!preverifyOk) {
-    // OpenSSL verification failure, no need to call CertificateIdentityVerifier
+    // Verification failed (either OpenSSL or verifyContext), no need to call
+    // verifyLeaf.
     return 0;
   }
 
-  // only invoke the CertificateIdentityVerifier for the leaf certificate and
-  // only if OpenSSL's preverify and the HandshakeCB's handshakeVer succeeded
+  // only invoke the verifyLeaf callback for the leaf certificate and
+  // only if all previous verification steps succeeded (OpenSSL, handshakeVer,
+  // and verifyContext)
 
   int currentDepth = X509_STORE_CTX_get_error_depth(x509Ctx);
   if (currentDepth != 0 || self->certificateIdentityVerifier_ == nullptr) {
diff --git a/third-party/folly/src/folly/io/async/AsyncSSLSocket.h b/third-party/folly/src/folly/io/async/AsyncSSLSocket.h
@@ -198,10 +198,12 @@ class AsyncSSLSocket : public AsyncSocket {
    * Struct to consolidate constructor arguments.
    */
   struct Options {
-    // If this verifier is set, it's used during the TLS handshake. It will be
-    // invoked to verify the peer's end-entity leaf certificate after OpenSSL's
-    // chain validation and after calling the HandshakeCB's handshakeVer() and
-    // only if these are successful.
+    // If this verifier is set, it's used during the TLS handshake. First,
+    // verifyContext() is called during OpenSSL's certificate verification
+    // callback for each certificate in the chain, after HandshakeCB's
+    // handshakeVer() if set. Then, verifyLeaf() is invoked to verify the
+    // peer's end-entity leaf certificate, but only if OpenSSL's chain
+    // validation, handshakeVer(), and verifyContext() all succeeded.
     std::shared_ptr<CertificateIdentityVerifier> verifier;
     bool deferSecurityNegotiation{};
     bool isServer{};
diff --git a/third-party/folly/src/folly/io/async/CertificateIdentityVerifier.h b/third-party/folly/src/folly/io/async/CertificateIdentityVerifier.h
@@ -16,18 +16,27 @@
 
 #pragma once
 
-#include <folly/Try.h>
-#include <folly/Unit.h>
+#include <memory>
+
 #include <folly/io/async/AsyncTransportCertificate.h>
+#include <folly/portability/OpenSSL.h>
 
 namespace folly {
 
 /**
  * CertificateIdentityVerifier implementations are used during TLS handshakes to
- * extract and verify end-entity certificate identities. AsyncSSLSocket first
- * performs OpenSSL certificate chain validation and then invokes any registered
- * HandshakeCB's handshakeVer() method. Only if both of these succeed, it then
- * calls the verifyLeaf method to further verify a peer's certificate.
+ * extract and verify end-entity certificate identities.
+ *
+ * During TLS handshake, AsyncSSLSocket performs verification in this order:
+ * 1. OpenSSL performs internal certificate chain validation
+ * 2. HandshakeCB's handshakeVer() is invoked (if registered)
+ * 3. CertificateIdentityVerifier's verifyContext() is invoked (if registered)
+ *    - Called once for EACH certificate in the chain (root → intermediate →
+ * leaf)
+ *    - Provides access to the full X509_STORE_CTX for chain inspection
+ * 4. CertificateIdentityVerifier's verifyLeaf() is invoked (if registered)
+ *    - Called ONLY for the leaf certificate at depth 0
+ *    - Only if all previous verification steps succeeded
  *
  * TLS connections must pass all these checks in order for an AsyncSSLSocket's
  * registered HandshakeCB to receive handshakeSuc().
@@ -39,6 +48,50 @@ class CertificateIdentityVerifier {
  public:
   virtual ~CertificateIdentityVerifier() = default;
 
+  /**
+   * AsyncSSLSocket calls verifyContext() during the OpenSSL certificate
+   * verification callback for EACH certificate in the chain (typically
+   * root → intermediate(s) → leaf).
+   *
+   * This method allows custom validation logic beyond OpenSSL's internal
+   * consistency checks. The returned value becomes the new verification state:
+   * - If this method returns false, verification fails and verifyLeaf() will
+   *   NOT be called
+   * - If this method returns true, verification succeeds (and verifyLeaf()
+   *   may be called for the leaf certificate at depth 0)
+   *
+   * This method can override OpenSSL's verification result. For example:
+   * - If OpenSSL fails (preverifyOk=false) but verifyContext returns true,
+   *   verification succeeds and verifyLeaf() may be called
+   * - If OpenSSL succeeds (preverifyOk=true) but verifyContext returns false,
+   *   verification fails and verifyLeaf() will NOT be called
+   *
+   * Unlike HandshakeCB::handshakeVer(), this method does not short-circuit
+   * when it changes the result - it updates the verification state and allows
+   * processing to continue.
+   *
+   * The default implementation returns preverifyOk unchanged (pass-through),
+   * deferring to OpenSSL's verification decision.
+   *
+   * IMPORTANT: This method is called multiple times per handshake - once for
+   * each certificate in the chain. Use X509_STORE_CTX_get_error_depth(ctx)
+   * to determine the depth of the certificate being verified.
+   *
+   * See the passages on verify_callback in SSL_CTX_set_verify(3) for more
+   * details.
+   *
+   * @param preverifyOk Result of OpenSSL's internal verification checks
+   * @param ctx OpenSSL verification context containing the certificate chain
+   *            and verification state. Use
+   * X509_STORE_CTX_get_current_cert(&ctx) to access the certificate being
+   * verified at this depth.
+   * @return true if the certificate context is valid, false otherwise
+   */
+  virtual bool verifyContext(
+      bool preverifyOk, [[maybe_unused]] X509_STORE_CTX& ctx) const noexcept {
+    return preverifyOk;
+  }
+
   /**
    * AsyncSSLSocket calls verifyLeaf() during a TLS handshake after chain
    * verification, only if certificate verification is required/requested,
diff --git a/third-party/folly/src/folly/io/async/test/AsyncSSLSocketTest.cpp b/third-party/folly/src/folly/io/async/test/AsyncSSLSocketTest.cpp
@@ -1485,12 +1485,18 @@ TEST(AsyncSSLSocketTest, SSLCertificateIdentityVerifierReturns) {
   std::shared_ptr<MockCertificateIdentityVerifier> verifier =
       std::make_shared<MockCertificateIdentityVerifier>();
 
+  // expecting context verification to be called first
+  auto&& verifyContext =
+      EXPECT_CALL(*verifier, verifyContext(true, _))
+          .Times(AtLeast(1))
+          .WillRepeatedly(Return(true));
   // expecting to only verify once, with the leaf certificate
   // (kTestCert)
   EXPECT_CALL(
       *verifier,
       verifyLeaf(Property(
           &AsyncTransportCertificate::getIdentity, StrEq("Asox Company"))))
+      .After(verifyContext)
       .WillOnce(Return(ByMove(
           std::make_unique<folly::ssl::BasicTransportCertificate>(
               "Asox Company", readCertFromFile(kTestCert)))));
@@ -1542,11 +1548,18 @@ TEST(AsyncSSLSocketTest, SSLCertificateIdentityVerifierFailsToConnect) {
   // Throw an exception on verification failure
   CertificateIdentityVerifierException failed{"a failed test reason"};
 
+  // expecting context verification to be called first
+  auto&& verifyContext =
+      EXPECT_CALL(*verifier, verifyContext(true, _))
+          .Times(AtLeast(1))
+          .WillRepeatedly(Return(true));
+
   // expecting to only verify once, with the leaf certificate (kTestCert)
   EXPECT_CALL(
       *verifier,
       verifyLeaf(Property(
           &AsyncTransportCertificate::getIdentity, StrEq("Asox Company"))))
+      .After(verifyContext)
       .WillOnce(Throw(failed));
 
   AsyncSSLSocket::Options opts;
@@ -1562,6 +1575,119 @@ TEST(AsyncSSLSocketTest, SSLCertificateIdentityVerifierFailsToConnect) {
   socket->close();
 }
 
+/**
+ * Verify that the client fails to connect during handshake when
+ * CertificateIdentityVerifier::verifyContext returns false,
+ * and that verifyLeaf is not invoked when verifyContext fails.
+ */
+TEST(AsyncSSLSocketTest, SSLCertificateIdentityVerifierContextFailure) {
+  EventBase eventBase;
+  auto clientCtx = std::make_shared<folly::SSLContext>();
+  auto serverCtx = std::make_shared<folly::SSLContext>();
+  getctx(clientCtx, serverCtx);
+  // the client socket will default to USE_CTX, so set VERIFY here
+  clientCtx->setVerificationOption(SSLContext::SSLVerifyPeerEnum::VERIFY);
+  // load root certificate
+  clientCtx->loadTrustedCertificates(find_resource(kTestCA).c_str());
+
+  // prepare a basic server (callbacks have a few EXPECTS to fulfill)
+  ReadCallback readCallback(nullptr);
+  // expects a failed handshake
+  HandshakeCallback handshakeCallback(
+      &readCallback, HandshakeCallback::ExpectType::EXPECT_ERROR);
+  SSLServerAcceptCallback acceptCallback(&handshakeCallback);
+  TestSSLServer server(&acceptCallback, serverCtx);
+
+  std::shared_ptr<StrictMock<MockCertificateIdentityVerifier>> verifier =
+      std::make_shared<StrictMock<MockCertificateIdentityVerifier>>();
+
+  // verifyContext should be called and return false to fail verification
+  EXPECT_CALL(*verifier, verifyContext(true, _)).WillOnce(Return(false));
+
+  // verifyLeaf should NOT be called since verifyContext failed
+  EXPECT_CALL(*verifier, verifyLeaf).Times(0);
+
+  AsyncSSLSocket::Options opts;
+  opts.verifier = std::move(verifier);
+
+  // connect to server and handshake
+  AsyncSSLSocket::UniquePtr socket(
+      new AsyncSSLSocket(clientCtx, &eventBase, std::move(opts)));
+  socket->connect(nullptr, server.getAddress(), 0);
+
+  eventBase.loop();
+
+  socket->close();
+}
+
+/**
+ * Verify that verifyContext has access to the X509_STORE_CTX
+ * and can inspect the certificate chain.
+ */
+TEST(AsyncSSLSocketTest, SSLCertificateIdentityVerifierContextInspectsChain) {
+  EventBase eventBase;
+  auto clientCtx = std::make_shared<folly::SSLContext>();
+  auto serverCtx = std::make_shared<folly::SSLContext>();
+  getctx(clientCtx, serverCtx);
+  // the client socket will default to USE_CTX, so set VERIFY here
+  clientCtx->setVerificationOption(SSLContext::SSLVerifyPeerEnum::VERIFY);
+  // load root certificate
+  clientCtx->loadTrustedCertificates(find_resource(kTestCA).c_str());
+
+  // prepare a basic server (callbacks have a few EXPECTS to fulfill)
+  ReadCallback readCallback(nullptr);
+  // expects successful handshake
+  HandshakeCallback handshakeCallback(&readCallback);
+  SSLServerAcceptCallback acceptCallback(&handshakeCallback);
+  TestSSLServer server(&acceptCallback, serverCtx);
+
+  std::shared_ptr<MockCertificateIdentityVerifier> verifier =
+      std::make_shared<MockCertificateIdentityVerifier>();
+
+  // verifyContext should be called and have access to X509_STORE_CTX
+  auto&& verifyContext =
+      EXPECT_CALL(*verifier, verifyContext(true, _))
+          .Times(AtLeast(1))
+          .WillRepeatedly(WithArg<1>([](X509_STORE_CTX& ctx) {
+            // Verify we can access the cert chain
+            X509* cert = X509_STORE_CTX_get_current_cert(&ctx);
+            EXPECT_NE(cert, nullptr);
+
+            // Verify we can get the chain depth
+            int depth = X509_STORE_CTX_get_error_depth(&ctx);
+            EXPECT_GE(depth, 0);
+
+            return true;
+          }));
+
+  // expecting to verify leaf certificate after context verification
+  EXPECT_CALL(
+      *verifier,
+      verifyLeaf(Property(
+          &AsyncTransportCertificate::getIdentity, StrEq("Asox Company"))))
+      .After(verifyContext)
+      .WillOnce(Return(ByMove(
+          std::make_unique<folly::ssl::BasicTransportCertificate>(
+              "Asox Company", readCertFromFile(kTestCert)))));
+
+  AsyncSSLSocket::Options opts;
+  opts.verifier = std::move(verifier);
+
+  // connect to server and handshake
+  AsyncSSLSocket::UniquePtr socket(
+      new AsyncSSLSocket(clientCtx, &eventBase, std::move(opts)));
+  socket->connect(nullptr, server.getAddress(), 0);
+
+  // write to satisfy server ReadCallback EXPECTs
+  std::array<uint8_t, 128> buf;
+  memset(buf.data(), 'a', buf.size());
+  socket->write(nullptr, buf.data(), buf.size());
+
+  eventBase.loop();
+
+  socket->close();
+}
+
 /**
  * Verify that the client's CertificateIdentityVerifier is not invoked if
  * OpenSSL's verification fails. (With no HandshakeCB.)
@@ -1583,9 +1709,10 @@ TEST(AsyncSSLSocketTest, SSLCertificateIdentityVerifierNotInvokedX509Failure) {
   SSLServerAcceptCallback acceptCallback(&handshakeCallback);
   TestSSLServer server(&acceptCallback, serverCtx);
 
-  // should not get called
+  // do not override verification result
   std::shared_ptr<StrictMock<MockCertificateIdentityVerifier>> verifier =
       std::make_shared<StrictMock<MockCertificateIdentityVerifier>>();
+  EXPECT_CALL(*verifier, verifyContext(false, _)).WillOnce(Return(false));
 
   AsyncSSLSocket::Options opts;
   opts.verifier = std::move(verifier);
@@ -1622,9 +1749,12 @@ TEST(
   AsyncSocket::UniquePtr rawClient(new AsyncSocket(&eventBase, fds[0]));
   AsyncSocket::UniquePtr rawServer(new AsyncSocket(&eventBase, fds[1]));
 
-  // should not be invoked
+  // should be invoked to only verify context
   std::shared_ptr<StrictMock<MockCertificateIdentityVerifier>> verifier =
       std::make_shared<StrictMock<MockCertificateIdentityVerifier>>();
+  EXPECT_CALL(*verifier, verifyContext)
+      .Times(AtLeast(1))
+      .WillRepeatedly(Return(true));
 
   AsyncSSLSocket::Options clientOpts;
   clientOpts.verifier = verifier;
@@ -1645,14 +1775,14 @@ TEST(
   // to be considered as unsuccessful
   EXPECT_CALL(clientHandshakeCB, handshakeVerImpl(clientSock.get(), true, _))
       .Times(AtLeast(1))
-      .WillRepeatedly(Invoke([&](auto&&, bool preverifyOk, auto&& ctx) {
+      .WillRepeatedly([&](auto&&, bool preverifyOk, auto&& ctx) {
         auto currentDepth = X509_STORE_CTX_get_error_depth(ctx);
         if (currentDepth == 0) {
           EXPECT_TRUE(preverifyOk);
           return false;
         }
         return preverifyOk;
-      }));
+      });
 
   // failure callback to verify handshake failed
   EXPECT_CALL(clientHandshakeCB, handshakeErrImpl(clientSock.get(), _));
@@ -1695,19 +1825,29 @@ TEST(AsyncSSLSocketTest, SSLCertificateIdentityVerifierSucceedsOnServer) {
   // client and server verifiers should verify only once each
   std::shared_ptr<MockCertificateIdentityVerifier> clientVerifier =
       std::make_shared<MockCertificateIdentityVerifier>();
+  auto&& clientVerifyContext =
+      EXPECT_CALL(*clientVerifier, verifyContext(true, _))
+          .Times(AtLeast(1))
+          .WillRepeatedly(Return(true));
   EXPECT_CALL(
       *clientVerifier,
       verifyLeaf(Property(
           &AsyncTransportCertificate::getIdentity, StrEq("Asox Company"))))
+      .After(clientVerifyContext)
       .WillOnce(Return(ByMove(
           std::make_unique<folly::ssl::BasicTransportCertificate>(
               "Asox Company", readCertFromFile(kTestCert)))));
   std::shared_ptr<StrictMock<MockCertificateIdentityVerifier>> serverVerifier =
       std::make_shared<StrictMock<MockCertificateIdentityVerifier>>();
+  auto&& serverVerifyContext =
+      EXPECT_CALL(*serverVerifier, verifyContext(true, _))
+          .Times(AtLeast(1))
+          .WillRepeatedly(Return(true));
   EXPECT_CALL(
       *serverVerifier,
       verifyLeaf(Property(
           &AsyncTransportCertificate::getIdentity, StrEq("Asox Company"))))
+      .After(serverVerifyContext)
       .WillOnce(Return(ByMove(
           std::make_unique<folly::ssl::BasicTransportCertificate>(
               "Asox Company", readCertFromFile(kTestCert)))));
diff --git a/third-party/folly/src/folly/io/async/test/AsyncSSLSocketTest.h b/third-party/folly/src/folly/io/async/test/AsyncSSLSocketTest.h
@@ -495,11 +495,16 @@ class EmptyReadCallback : public ReadCallback {
 
 class MockCertificateIdentityVerifier : public CertificateIdentityVerifier {
  public:
+  MOCK_METHOD(
+      bool,
+      verifyContext,
+      (bool, X509_STORE_CTX&),
+      (const, noexcept, override));
   MOCK_METHOD(
       std::unique_ptr<AsyncTransportCertificate>,
       verifyLeaf,
       (const AsyncTransportCertificate&),
-      (const));
+      (const, override));
 };
 
 class MockHandshakeCB : public AsyncSSLSocket::HandshakeCB {
