Add a CertificateIdentityVerifier to AsyncSSLSocket

Summary:
This diff introduces a callback, `CertificateIdentityVerifier` that can probe peer end-entity certificates during a TLS handshake in `AsyncSSLSocket`.

The verifier gets called only if regular chain verification (OpenSSL's and a `HandshakeCB`'s) succeeds and can return a `Try` with a `CertificateIdentityVerifierException` to indicate that a failure occurred. `AsyncSSLSocket` will then fail the TLS handshake.

The diff also adds a new `AsyncSSLSocket` constructor with a new `Options` parameter that groups together some optional properties, including the verifier. We can eventually refactor the other constructors to use it too.

Reviewed By: mingtaoy

Differential Revision: D22821714

fbshipit-source-id: b63b141862b5703eb5274fb6ef8aa98934a55df0

folly/io/async/AsyncSSLSocket.cpp

@@ -209,6 +209,47 @@ class AsyncSSLSocketConnector : public AsyncSocket::ConnectCallback,
   }
 };
 
+AsyncSSLSocket::AsyncSSLSocket(
+    shared_ptr<SSLContext> ctx,
+    EventBase* evb,
+    Options&& options)
+    : AsyncSocket(evb),
+      server_{options.isServer},
+      ctx_{std::move(ctx)},
+      certificateIdentityVerifier_{std::move(options.verifier)},
+      handshakeTimeout_{this, evb},
+      connectionTimeout_{this, evb} {
+  init();
+  if (options.isServer) {
+    SSL_CTX_set_info_callback(
+        ctx_->getSSLCtx(), AsyncSSLSocket::sslInfoCallback);
+  }
+  if (options.deferSecurityNegotiation) {
+    sslState_ = STATE_UNENCRYPTED;
+  }
+}
+
+AsyncSSLSocket::AsyncSSLSocket(
+    std::shared_ptr<folly::SSLContext> ctx,
+    AsyncSocket::UniquePtr oldAsyncSocket,
+    Options&& options)
+    : AsyncSocket(std::move(oldAsyncSocket)),
+      server_{options.isServer},
+      ctx_{std::move(ctx)},
+      certificateIdentityVerifier_{std::move(options.verifier)},
+      handshakeTimeout_{this, AsyncSocket::getEventBase()},
+      connectionTimeout_{this, AsyncSocket::getEventBase()} {
+  noTransparentTls_ = true;
+  init();
+  if (options.isServer) {
+    SSL_CTX_set_info_callback(
+        ctx_->getSSLCtx(), AsyncSSLSocket::sslInfoCallback);
+  }
+  if (options.deferSecurityNegotiation) {
+    sslState_ = STATE_UNENCRYPTED;
+  }
+}
+
 /**
  * Create a client AsyncSSLSocket
  */
@@ -1805,9 +1846,51 @@ int AsyncSSLSocket::sslVerifyCallback(
   VLOG(3) << "AsyncSSLSocket::sslVerifyCallback() this=" << self << ", "
           << "fd=" << self->fd_ << ", preverifyOk=" << preverifyOk;
 
-  return (self->handshakeCallback_)
-      ? self->handshakeCallback_->handshakeVer(self, preverifyOk, x509Ctx)
-      : preverifyOk;
+  if (self->handshakeCallback_) {
+    int callbackOk =
+        (self->handshakeCallback_->handshakeVer(self, preverifyOk, x509Ctx))
+        ? 1
+        : 0;
+
+    if (preverifyOk != callbackOk) {
+      // HandshakeCB overwrites result from OpenSSL. One way or another, do not
+      // call CertificateIdentityVerifier.
+      return callbackOk;
+    }
+  }
+
+  if (!preverifyOk) {
+    // OpenSSL verification failure, no need to call CertificateIdentityVerifier
+    return 0;
+  }
+
+  // only invoke the CertificateIdentityVerifier for the leaf certificate and
+  // only if OpenSSL's preverify and the HandshakeCB's handshakeVer succeeded
+
+  int currentDepth = X509_STORE_CTX_get_error_depth(x509Ctx);
+  if (currentDepth != 0 || self->certificateIdentityVerifier_ == nullptr) {
+    return 1;
+  }
+
+  X509* peerX509 = X509_STORE_CTX_get_current_cert(x509Ctx);
+  X509_up_ref(peerX509);
+  folly::ssl::X509UniquePtr peer{peerX509};
+  auto cn = OpenSSLUtils::getCommonName(peerX509);
+  auto cert = std::make_unique<BasicTransportCertificate>(
+      std::move(cn), std::move(peer));
+
+  auto certVerifyResult =
+      self->certificateIdentityVerifier_->verifyLeaf(*cert.get());
+
+  if (certVerifyResult.hasException()) {
+    LOG(ERROR) << "AsyncSSLSocket::sslVerifyCallback(this=" << self
+               << ", fd=" << self->fd_
+               << ") Failed to verify leaf certificate identity(ies): "
+               << folly::exceptionStr(certVerifyResult.exception());
+    return 0;
+  }
+
+  return 1;
 }
 
 void AsyncSSLSocket::enableClientHelloParsing() {

folly/io/async/AsyncSSLSocket.h

@@ -26,6 +26,7 @@
 #include <folly/io/async/AsyncPipe.h>
 #include <folly/io/async/AsyncSocket.h>
 #include <folly/io/async/AsyncTimeout.h>
+#include <folly/io/async/CertificateIdentityVerifier.h>
 #include <folly/io/async/SSLContext.h>
 #include <folly/io/async/TimeoutManager.h>
 #include <folly/io/async/ssl/OpenSSLUtils.h>
@@ -196,6 +197,40 @@ class AsyncSSLSocket : public AsyncSocket {
     DestructorGuard dg_;
   };
 
+  /**
+   * 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.
+    std::shared_ptr<CertificateIdentityVerifier> verifier;
+    bool deferSecurityNegotiation{};
+    bool isServer{};
+  };
+
+  /**
+   * Initialize this AsyncSSLSocket object with the given Options.
+   *
+   * @param options optional arguments for this AsyncSSLSocket instance
+   */
+  AsyncSSLSocket(
+      std::shared_ptr<folly::SSLContext> ctx,
+      EventBase* evb,
+      Options&& options);
+
+  /**
+   * Initialize this AsyncSSLSocket object with the given Options from an
+   * already connected AsyncSocket.
+   *
+   * @param options optional arguments for this AsyncSSLSocket instance
+   */
+  AsyncSSLSocket(
+      std::shared_ptr<folly::SSLContext> ctx,
+      AsyncSocket::UniquePtr oldAsyncSocket,
+      Options&& options);
+
   /**
    * Create a client AsyncSSLSocket
    */
@@ -927,6 +962,7 @@ class AsyncSSLSocket : public AsyncSocket {
   std::shared_ptr<folly::SSLContext> ctx_;
   // Callback for SSL_accept() or SSL_connect()
   HandshakeCB* handshakeCallback_{nullptr};
+  std::shared_ptr<CertificateIdentityVerifier> certificateIdentityVerifier_;
   ssl::SSLUniquePtr ssl_;
   Timeout handshakeTimeout_;
   Timeout connectionTimeout_;

folly/io/async/CertificateIdentityVerifier.h

+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <folly/Try.h>
+#include <folly/Unit.h>
+#include <folly/io/async/AsyncTransportCertificate.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.
+ *
+ * TLS connections must pass all these checks in order for an AsyncSSLSocket's
+ * registered HandshakeCB to receive handshakeSuc().
+ *
+ * Instances can be shared across AsyncSSLSockets so implementations should be
+ * thread-safe.
+ */
+class CertificateIdentityVerifier {
+ public:
+  virtual ~CertificateIdentityVerifier() = default;
+
+  /**
+   * AsyncSSLSocket calls verifyLeaf() during a TLS handshake after chain
+   * verification, only if certificate verification is required/requested,
+   * with the peer's leaf certificate provided as an argument.
+   *
+   * Returns an Try with a CertificateIdentityVerifierException set if
+   * verification fails.
+   *
+   * @param leafCertificate leaf X509 certificate of the connected peer
+   */
+  FOLLY_NODISCARD virtual Try<Unit> verifyLeaf(
+      const AsyncTransportCertificate& leafCertificate) const noexcept = 0;
+};
+
+/**
+ * Base of exception hierarchy for CertificateIdentityVerifier failure reasons.
+ */
+class FOLLY_EXPORT CertificateIdentityVerifierException
+    : public std::runtime_error {
+ public:
+  using std::runtime_error::runtime_error;
+};
+
+} // namespace folly

folly/io/async/test/AsyncSSLSocketTest.h

@@ -31,6 +31,7 @@
 #include <folly/io/async/EventBase.h>
 #include <folly/io/async/ssl/SSLErrors.h>
 #include <folly/io/async/test/TestSSLServer.h>
+#include <folly/portability/GMock.h>
 #include <folly/portability/GTest.h>
 #include <folly/portability/PThread.h>
 #include <folly/portability/Sockets.h>
@@ -538,6 +539,43 @@ class EmptyReadCallback : public ReadCallback {
   std::shared_ptr<AsyncSocket> tcpSocket_;
 };
 
+class MockCertificateIdentityVerifier : public CertificateIdentityVerifier {
+ public:
+  MOCK_CONST_METHOD1(
+      verifyLeafImpl,
+      Try<Unit>(const AsyncTransportCertificate&));
+  // decorate to add noexcept
+  virtual Try<Unit> verifyLeaf(const AsyncTransportCertificate& leafCertificate)
+      const noexcept override {
+    return verifyLeafImpl(leafCertificate);
+  }
+};
+
+class MockHandshakeCB : public AsyncSSLSocket::HandshakeCB {
+ public:
+  MOCK_METHOD3(handshakeVerImpl, bool(AsyncSSLSocket*, bool, X509_STORE_CTX*));
+  virtual bool handshakeVer(
+      AsyncSSLSocket* sock,
+      bool preverifyOk,
+      X509_STORE_CTX* ctx) noexcept override {
+    return handshakeVerImpl(sock, preverifyOk, ctx);
+  }
+
+  MOCK_METHOD1(handshakeSucImpl, void(AsyncSSLSocket*));
+  virtual void handshakeSuc(AsyncSSLSocket* sock) noexcept override {
+    handshakeSucImpl(sock);
+  }
+
+  MOCK_METHOD2(
+      handshakeErrImpl,
+      void(AsyncSSLSocket*, const AsyncSocketException&));
+  virtual void handshakeErr(
+      AsyncSSLSocket* sock,
+      const AsyncSocketException& ex) noexcept override {
+    handshakeErrImpl(sock, ex);
+  }
+};
+
 class HandshakeCallback : public AsyncSSLSocket::HandshakeCB {
  public:
   enum ExpectType { EXPECT_SUCCESS, EXPECT_ERROR };