[tls] Add a custom listener handshaker for TLS.

api/envoy/extensions/transport_sockets/tls/v3/tls.proto

@@ -238,4 +238,7 @@ message CommonTlsContext {
   //
   // There is no default for this parameter. If empty, Envoy will not expose ALPN.
   repeated string alpn_protocols = 4;
+
+  // Custom TLS handshaker. If empty, defaults to native TLS handshaker.
+  config.core.v3.TypedExtensionConfig custom_listener_handshaker = 13;
 }

include/envoy/ssl/BUILD

@@ -28,6 +28,7 @@ envoy_cc_library(
     hdrs = ["context_config.h"],
     deps = [
         ":certificate_validation_context_config_interface",
+        ":handshaker_interface",
         ":tls_certificate_config_interface",
     ],
 )
@@ -68,3 +69,21 @@ envoy_cc_library(
     deps = [
     ],
 )
+
+envoy_cc_library(
+    name = "handshaker_interface",
+    hdrs = ["handshaker.h"],
+    external_deps = ["ssl"],
+    deps = [
+        ":socket_state",
+        "//include/envoy/config:typed_config_interface",
+        "//include/envoy/network:transport_socket_interface",
+        "//include/envoy/protobuf:message_validator_interface",
+    ],
+)
+
+envoy_cc_library(
+    name = "socket_state",
+    hdrs = ["socket_state.h"],
+    deps = [],
+)

include/envoy/ssl/context_config.h

@@ -8,6 +8,7 @@
 
 #include "envoy/common/pure.h"
 #include "envoy/ssl/certificate_validation_context_config.h"
+#include "envoy/ssl/handshaker.h"
 #include "envoy/ssl/tls_certificate_config.h"
 
 #include "absl/types/optional.h"
@@ -73,6 +74,17 @@ class ContextConfig {
    * @param callback callback that is executed by context config.
    */
   virtual void setSecretUpdateCallback(std::function<void()> callback) PURE;
+
+  /**
+   * @return the handshaker to use for TLS handshakes.
+   */
+  virtual Ssl::HandshakerSharedPtr createHandshaker(bssl::UniquePtr<SSL> ssl) const PURE;
+
+  /**
+   * @return whether or not this context requires certificates for TLS
+   * handshakes.
+   */
+  virtual bool requireCertificates() const PURE;
 };
 
 class ClientContextConfig : public virtual ContextConfig {

include/envoy/ssl/handshaker.h

@@ -0,0 +1,101 @@
+#pragma once
+
+#include "envoy/api/api.h"
+#include "envoy/common/pure.h"
+#include "envoy/config/typed_config.h"
+#include "envoy/network/transport_socket.h"
+#include "envoy/protobuf/message_validator.h"
+#include "envoy/ssl/socket_state.h"
+
+#include "openssl/ssl.h"
+
+namespace Envoy {
+namespace Ssl {
+
+class HandshakerCallbacks {
+public:
+  virtual ~HandshakerCallbacks() = default;
+
+  /**
+   * Called when a handshake is successfully performed.
+   */
+  virtual void onSuccessCb(SSL* ssl) PURE;
+  /**
+   * Called when a handshake fails.
+   */
+  virtual void onFailureCb() PURE;
+};
+
+/*
+ * Interface for a Handshaker which is responsible for owning the
+ * `bssl::UniquePtr<SSL>` and performing handshakes.
+ */
+class Handshaker {
+public:
+  virtual ~Handshaker() = default;
+
+  /**
+   * Do the handshake.
+   *
+   * NB: |state| is a mutable reference.
+   */
+  virtual Network::PostIoAction doHandshake(SocketState& state) PURE;
+
+  /**
+   * Set internal pointers to  Network::TransportSocketCallbacks and
+   * Ssl::HandshakerCallbacks.
+   * Depending on impl, these callbacks can be invoked to access connection
+   * state, raise connection events, etc.
+   */
+  virtual void setCallbacks(Network::TransportSocketCallbacks& callbacks,
+                            Ssl::HandshakerCallbacks& handshaker_callbacks) PURE;
+
+  /*
+   * Access the held SSL object as a ptr. Callsites should handle nullptr
+   * gracefully.
+   */
+  virtual SSL* ssl() PURE;
+};
+
+using HandshakerSharedPtr = std::shared_ptr<Handshaker>;
+
+class HandshakerFactoryContext {
+public:
+  virtual ~HandshakerFactoryContext() = default;
+
+  /**
+   * @return reference to the Api object
+   */
+  virtual Api::Api& api() PURE;
+
+  /**
+   * The list of supported protocols exposed via ALPN, from ContextConfig.
+   */
+  virtual absl::string_view alpnProtocols() const PURE;
+};
+
+using HandshakerFactoryCb = std::function<HandshakerSharedPtr(bssl::UniquePtr<SSL>)>;
+
+class HandshakerFactory : public Config::TypedFactory {
+public:
+  /**
+   * @returns a callback (of type HandshakerFactoryCb). Accepts the |config| and
+   * |validation_visitor| for early config validation. This virtual base doesn't
+   * perform MessageUtil::downcastAndValidate, but an implementation should.
+   */
+  virtual HandshakerFactoryCb
+  createHandshakerCb(const Protobuf::Message& message,
+                     HandshakerFactoryContext& handshaker_factory_context,
+                     ProtobufMessage::ValidationVisitor& validation_visitor) PURE;
+
+  std::string category() const override { return "envoy.tls_handshakers"; }
+
+  /**
+   * Implementations should return true if the tls context accompanying this
+   * handshaker expects certificates.
+   */
+  virtual bool requireCertificates() const PURE;
+};
+
+} // namespace Ssl
+} // namespace Envoy

include/envoy/ssl/socket_state.h

@@ -0,0 +1,9 @@
+#pragma once
+
+namespace Envoy {
+namespace Ssl {
+
+enum class SocketState { PreHandshake, HandshakeInProgress, HandshakeComplete, ShutdownSent };
+
+} // namespace Ssl
+} // namespace Envoy

source/extensions/transport_sockets/tls/BUILD

@@ -40,9 +40,12 @@ envoy_cc_library(
     deps = [
         ":context_config_lib",
         ":context_lib",
+        ":handshaker_lib",
         ":utility_lib",
         "//include/envoy/network:connection_interface",
         "//include/envoy/network:transport_socket_interface",
+        "//include/envoy/ssl:handshaker_interface",
+        "//include/envoy/ssl:socket_state",
         "//include/envoy/ssl:ssl_socket_extended_info_interface",
         "//include/envoy/ssl/private_key:private_key_callbacks_interface",
         "//include/envoy/ssl/private_key:private_key_interface",
@@ -63,6 +66,7 @@ envoy_cc_library(
         "ssl",
     ],
     deps = [
+        ":handshaker_lib",
         "//include/envoy/secret:secret_callbacks_interface",
         "//include/envoy/secret:secret_provider_interface",
         "//include/envoy/server:transport_socket_config_interface",
@@ -118,6 +122,35 @@ envoy_cc_library(
     ],
 )
 
+envoy_cc_library(
+    name = "handshaker_lib",
+    srcs = ["handshaker_impl.cc"],
+    hdrs = ["handshaker_impl.h"],
+    external_deps = [
+        "ssl",
+    ],
+    deps = [
+        "//include/envoy/ssl:context_config_interface",
+        "//include/envoy/ssl:context_interface",
+        "//include/envoy/ssl:context_manager_interface",
+        "//include/envoy/ssl:handshaker_interface",
+        "//include/envoy/ssl:socket_state",
+        "//include/envoy/ssl:ssl_socket_extended_info_interface",
+        "//include/envoy/ssl/private_key:private_key_interface",
+        "//include/envoy/stats:stats_interface",
+        "//include/envoy/stats:stats_macros",
+        "//source/common/common:assert_lib",
+        "//source/common/common:base64_lib",
+        "//source/common/common:hex_lib",
+        "//source/common/common:utility_lib",
+        "//source/common/network:address_lib",
+        "//source/common/protobuf:utility_lib",
+        "//source/common/stats:symbol_table_lib",
+        "//source/common/stats:utility_lib",
+        "//source/extensions/transport_sockets/tls/private_key:private_key_manager_lib",
+    ],
+)
+
 envoy_cc_library(
     name = "utility_lib",
     srcs = ["utility.cc"],

source/extensions/transport_sockets/tls/context_config_impl.cc

@@ -213,6 +213,25 @@ ContextConfigImpl::ContextConfigImpl(
       }
     }
   }
+
+  HandshakerFactoryContextImpl handshaker_factory_context(api_, alpnProtocols());
+  Ssl::HandshakerFactory* handshaker_factory;
+  if (config.has_custom_listener_handshaker()) {
+    // If a custom handshaker is configured, derive the factory from the config.
+    const auto& handshaker_config = config.custom_listener_handshaker();
+    handshaker_factory =
+        &Config::Utility::getAndCheckFactory<Ssl::HandshakerFactory>(handshaker_config);
+    handshaker_factory_cb_ = handshaker_factory->createHandshakerCb(
+        handshaker_config.typed_config(), handshaker_factory_context,
+        factory_context.messageValidationVisitor());
+  } else {
+    // Otherwise, derive the config from the (default) factory).
+    handshaker_factory = HandshakerFactoryImpl::getDefaultHandshakerFactory();
+    handshaker_factory_cb_ = handshaker_factory->createHandshakerCb(
+        *handshaker_factory->createEmptyConfigProto(), handshaker_factory_context,
+        factory_context.messageValidationVisitor());
+  }
+  require_certificates_ = handshaker_factory->requireCertificates();
 }
 
 Ssl::CertificateValidationContextConfigPtr ContextConfigImpl::getCombinedValidationContextConfig(
@@ -224,6 +243,10 @@ Ssl::CertificateValidationContextConfigPtr ContextConfigImpl::getCombinedValidat
   return std::make_unique<Envoy::Ssl::CertificateValidationContextConfigImpl>(combined_cvc, api_);
 }
 
+Ssl::HandshakerSharedPtr ContextConfigImpl::createHandshaker(bssl::UniquePtr<SSL> ssl) const {
+  return handshaker_factory_cb_(std::move(ssl));
+}
+
 void ContextConfigImpl::setSecretUpdateCallback(std::function<void()> callback) {
   if (!tls_certificate_providers_.empty()) {
     if (tc_update_callback_handle_) {
@@ -404,7 +427,9 @@ ServerContextConfigImpl::ServerContextConfigImpl(
 
   if ((config.common_tls_context().tls_certificates().size() +
        config.common_tls_context().tls_certificate_sds_secret_configs().size()) == 0) {
-    throw EnvoyException("No TLS certificates found for server context");
+    if (requireCertificates()) {
+      throw EnvoyException("No TLS certificates found for server context");
+    }
   } else if (!config.common_tls_context().tls_certificates().empty() &&
              !config.common_tls_context().tls_certificate_sds_secret_configs().empty()) {
     throw EnvoyException("SDS and non-SDS TLS certificates may not be mixed in server contexts");

source/extensions/transport_sockets/tls/context_config_impl.h

@@ -13,6 +13,8 @@
 #include "common/json/json_loader.h"
 #include "common/ssl/tls_certificate_config_impl.h"
 
+#include "extensions/transport_sockets/tls/handshaker_impl.h"
+
 namespace Envoy {
 namespace Extensions {
 namespace TransportSockets {
@@ -60,6 +62,10 @@ class ContextConfigImpl : public virtual Ssl::ContextConfig {
       const envoy::extensions::transport_sockets::tls::v3::CertificateValidationContext&
           dynamic_cvc);
 
+  Ssl::HandshakerSharedPtr createHandshaker(bssl::UniquePtr<SSL> ssl) const override;
+
+  bool requireCertificates() const override { return require_certificates_; }
+
 protected:
   ContextConfigImpl(const envoy::extensions::transport_sockets::tls::v3::CommonTlsContext& config,
                     const unsigned default_min_protocol_version,
@@ -94,6 +100,9 @@ class ContextConfigImpl : public virtual Ssl::ContextConfig {
   Envoy::Common::CallbackHandle* cvc_validation_callback_handle_{};
   const unsigned min_protocol_version_;
   const unsigned max_protocol_version_;
+
+  Ssl::HandshakerFactoryCb handshaker_factory_cb_;
+  bool require_certificates_;
 };
 
 class ClientContextConfigImpl : public ContextConfigImpl, public Envoy::Ssl::ClientContextConfig {