[tls] Add a custom listener handshaker for TLS.

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

@@ -98,8 +98,13 @@ message DownstreamTlsContext {
   }];
 }
 
+// Custom config for customizing listener handshaker behavior.
+message CustomListenerHandshaker {
+  config.core.v3.TypedExtensionConfig typed_config = 1;
+}
+
 // TLS context shared by both client and server TLS contexts.
-// [#next-free-field: 11]
+// [#next-free-field: 12]
 message CommonTlsContext {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.auth.CommonTlsContext";
 
@@ -201,4 +206,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.
+  CustomListenerHandshaker custom_listener_handshaker = 11;
 }

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,20 @@ 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",
+    ],
+)
+
+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,11 @@ 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::HandshakerPtr createHandshaker() const PURE;
 };
 
 class ClientContextConfig : public virtual ContextConfig {

include/envoy/ssl/handshaker.h

@@ -0,0 +1,96 @@
+#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/ssl/socket_state.h"
+
+#include "openssl/ssl.h"
+
+namespace Envoy {
+namespace Ssl {
+
+class HandshakerCallbacks {
+public:
+  virtual ~HandshakerCallbacks() = default;
+
+  /**
+   * Hands off the internally-held SSL object for external manipulation.
+   */
+  virtual bssl::UniquePtr<SSL> Handoff() PURE;
+  /**
+   * Accepts an SSL object for internal storage.
+   */
+  virtual void Handback(bssl::UniquePtr<SSL> ssl) PURE;
+  /**
+   * Called when a handshake is successfully performed.
+   */
+  virtual void LogHandshake(SSL* ssl) PURE;
+  /**
+   * Called when a handshake fails.
+   */
+  virtual void ErrorCb() PURE;
+};
+
+class Handshaker {
+public:
+  virtual ~Handshaker() = default;
+
+  // The initialize method must be called with a non-null SSL* before
+  // doHandshake() is called.
+  virtual void initialize(SSL* ssl) PURE;
+
+  /**
+   * Do the handshake.
+   *
+   * NB: This method may be called with |ssl| == nullptr, for example during a
+   * reentrant call to doHandshake() during a period when the handshaker has
+   * handed off the SSL*.
+   *
+   * NB: |state| is mutable.
+   */
+  virtual Network::PostIoAction doHandshake(SocketState& state, SSL* ssl,
+                                            HandshakerCallbacks& callbacks) PURE;
+
+  /**
+   * Set an internal pointer to the Network::TransportSocketCallbacks struct.
+   * Depending on impl, these callbacks can be invoked to access connection
+   * state, raise connection events, etc.
+   */
+  virtual void setTransportSocketCallbacks(Network::TransportSocketCallbacks& callbacks) PURE;
+
+  /**
+   * Subclasses should return true if the tls context accompanying this
+   * handshaker expects certificates.
+   */
+  virtual bool requireCertificates() PURE;
+};
+
+using HandshakerPtr = std::unique_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;
+};
+
+class HandshakerFactory : public Config::TypedFactory {
+public:
+  virtual HandshakerPtr createHandshaker(const Protobuf::Message& config,
+                                         HandshakerFactoryContext& context) PURE;
+
+  std::string category() const override { return "envoy.handshakers"; }
+};
+
+} // 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,15 @@ ContextConfigImpl::ContextConfigImpl(
       }
     }
   }
+
+  if (config.has_custom_listener_handshaker()) {
+    auto& handshaker_config = config.custom_listener_handshaker().typed_config();
+    handshaker_factory_ =
+        &Config::Utility::getAndCheckFactory<Ssl::HandshakerFactory>(handshaker_config);
+    handshaker_config_message_ = Config::Utility::translateAnyToFactoryConfig(
+        handshaker_config.typed_config(), factory_context.messageValidationVisitor(),
+        *handshaker_factory_);
+  }
 }
 
 Ssl::CertificateValidationContextConfigPtr ContextConfigImpl::getCombinedValidationContextConfig(
@@ -224,6 +233,15 @@ Ssl::CertificateValidationContextConfigPtr ContextConfigImpl::getCombinedValidat
   return std::make_unique<Envoy::Ssl::CertificateValidationContextConfigImpl>(combined_cvc, api_);
 }
 
+Ssl::HandshakerPtr ContextConfigImpl::createHandshaker() const {
+  if (handshaker_factory_ == nullptr) {
+    return std::make_unique<HandshakerImpl>();
+  } else {
+    HandshakerFactoryContextImpl context(api_, alpnProtocols());
+    return handshaker_factory_->createHandshaker(*handshaker_config_message_, context);
+  }
+}
+
 void ContextConfigImpl::setSecretUpdateCallback(std::function<void()> callback) {
   if (!tls_certificate_providers_.empty()) {
     if (tc_update_callback_handle_) {
@@ -409,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 (createHandshaker()->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,8 @@ class ContextConfigImpl : public virtual Ssl::ContextConfig {
       const envoy::extensions::transport_sockets::tls::v3::CertificateValidationContext&
           dynamic_cvc);
 
+  Ssl::HandshakerPtr createHandshaker() const override;
+
 protected:
   ContextConfigImpl(const envoy::extensions::transport_sockets::tls::v3::CommonTlsContext& config,
                     const unsigned default_min_protocol_version,
@@ -94,6 +98,10 @@ class ContextConfigImpl : public virtual Ssl::ContextConfig {
   Envoy::Common::CallbackHandle* cvc_validation_callback_handle_{};
   const unsigned min_protocol_version_;
   const unsigned max_protocol_version_;
+
+  // Ptr to HandshakerFactory. If nullptr, uses default Handshaker impl.
+  Ssl::HandshakerFactory* handshaker_factory_{};
+  ProtobufTypes::MessagePtr handshaker_config_message_;
 };
 
 class ClientContextConfigImpl : public ContextConfigImpl, public Envoy::Ssl::ClientContextConfig {