tls: support BoringSSL private key async functionality

api/envoy/api/v2/auth/cert.proto

@@ -10,6 +10,8 @@ option go_package = "auth";
 import "envoy/api/v2/core/base.proto";
 import "envoy/api/v2/core/config_source.proto";
 
+import "google/protobuf/any.proto";
+import "google/protobuf/struct.proto";
 import "google/protobuf/wrappers.proto";
 
 import "validate/validate.proto";
@@ -102,6 +104,19 @@ message TlsParameters {
   repeated string ecdh_curves = 4;
 }
 
+message PrivateKeyMethod {
+  // Private key operations provider name. The name must match a
+  // supported private key operations provider type.
+  string provider_name = 1 [(validate.rules).string.min_bytes = 1];
+
+  // Private key operations provider specific configuration.
+  oneof config_type {
+    google.protobuf.Struct config = 2;
+
+    google.protobuf.Any typed_config = 4;
+  }
+}
+
 message TlsCertificate {
   // The TLS certificate chain.
   core.DataSource certificate_chain = 1;
@@ -118,6 +133,10 @@ message TlsCertificate {
 
   // [#not-implemented-hide:]
   repeated core.DataSource signed_certificate_timestamp = 5;
+
+  // BoringSSL private key operations. This is an alternative to private_key field. This can't be
+  // marked as "oneof" due to API compatibility reasons.
+  PrivateKeyMethod private_key_method = 6;
 }
 
 message TlsSessionTicketKeys {

include/envoy/ssl/BUILD

@@ -47,6 +47,9 @@ envoy_cc_library(
 envoy_cc_library(
     name = "tls_certificate_config_interface",
     hdrs = ["tls_certificate_config.h"],
+    deps = [
+        "//include/envoy/ssl/private_key:private_key_interface",
+    ],
 )
 
 envoy_cc_library(

include/envoy/ssl/context_manager.h

@@ -4,6 +4,7 @@
 
 #include "envoy/ssl/context.h"
 #include "envoy/ssl/context_config.h"
+#include "envoy/ssl/private_key/private_key.h"
 #include "envoy/stats/scope.h"
 
 namespace Envoy {
@@ -38,6 +39,12 @@ class ContextManager {
    * Iterate through all currently allocated contexts.
    */
   virtual void iterateContexts(std::function<void(const Context&)> callback) PURE;
+
+  /**
+   * Access the private key operations manager, which is part of SSL
+   * context manager.
+   */
+  virtual PrivateKeyOperationsManager& privateKeyOperationsManager() PURE;
 };
 
 } // namespace Ssl

include/envoy/ssl/private_key/BUILD

@@ -0,0 +1,35 @@
+licenses(["notice"])  # Apache 2
+
+load(
+    "//bazel:envoy_build_system.bzl",
+    "envoy_cc_library",
+    "envoy_package",
+)
+
+envoy_package()
+
+envoy_cc_library(
+    name = "private_key_interface",
+    hdrs = ["private_key.h"],
+    external_deps = ["ssl"],
+    deps = [
+        ":private_key_callbacks_interface",
+        "//include/envoy/event:dispatcher_interface",
+        "@envoy_api//envoy/api/v2/auth:cert_cc",
+    ],
+)
+
+envoy_cc_library(
+    name = "private_key_config_interface",
+    hdrs = ["private_key_config.h"],
+    deps = [
+        ":private_key_interface",
+        "//include/envoy/registry",
+    ],
+)
+
+envoy_cc_library(
+    name = "private_key_callbacks_interface",
+    hdrs = ["private_key_callbacks.h"],
+    external_deps = ["ssl"],
+)

include/envoy/ssl/private_key/private_key.h

@@ -0,0 +1,91 @@
+#pragma once
+
+#include <functional>
+#include <string>
+
+#include "envoy/api/v2/auth/cert.pb.h"
+#include "envoy/common/pure.h"
+#include "envoy/event/dispatcher.h"
+#include "envoy/ssl/private_key/private_key_callbacks.h"
+
+#include "openssl/ssl.h"
+
+namespace Envoy {
+namespace Server {
+namespace Configuration {
+// Prevent a dependency loop with the forward declaration.
+class TransportSocketFactoryContext;
+} // namespace Configuration
+} // namespace Server
+
+namespace Ssl {
+
+typedef std::shared_ptr<SSL_PRIVATE_KEY_METHOD> BoringSslPrivateKeyMethodSharedPtr;
+
+class PrivateKeyOperations {
+public:
+  virtual ~PrivateKeyOperations() {}
+
+  /**
+   * Associate the private key operations instance with a SSL connection.
+   * @param ssl a SSL connection object. The BoringSSL private key API
+   * doesn't allow passing user data to the asynchronous functions as a
+   * function parameter, so this enables the private key method provider
+   * to use SSL connection custom data fields instead.
+   */
+  virtual bool associateWithSsl(SSL* ssl) PURE;
+};
+
+typedef std::unique_ptr<PrivateKeyOperations> PrivateKeyOperationsPtr;
+
+class PrivateKeyOperationsProvider {
+public:
+  virtual ~PrivateKeyOperationsProvider() {}
+
+  /**
+   * Get a private key operations instance from the provider.
+   * @param cb a callbacks object, whose "complete" method will be invoked
+   * when the asynchronous processing is complete.
+   * @param dispatcher supplies the owning thread's dispatcher.
+   * @return the private key operations instance.
+   */
+  virtual PrivateKeyOperationsPtr getPrivateKeyOperations(SSL* ssl,
+                                                          PrivateKeyOperationsCallbacks& cb,
+                                                          Event::Dispatcher& dispatcher) PURE;
+
+  /**
+   * Get the private key methods from the provider.
+   * @return the private key methods associated with this provider and
+   * configuration.
+   */
+  virtual BoringSslPrivateKeyMethodSharedPtr getBoringSslPrivateKeyMethod() PURE;
+};
+
+typedef std::shared_ptr<PrivateKeyOperationsProvider> PrivateKeyOperationsProviderSharedPtr;
+
+/**
+ * A manager for finding correct user-provided functions for handling BoringSSL private key
+ * operations.
+ */
+class PrivateKeyOperationsManager {
+public:
+  virtual ~PrivateKeyOperationsManager() {}
+
+  /**
+   * Finds and returns a private key operations provider for BoringSSL.
+   *
+   * @param message a protobuf message object containing a
+   * PrivateKeyMethod message.
+   * @param private_key_provider_context context that provides components for creating and
+   * initializing connections for keyless TLS etc.
+   * @return PrivateKeyOperationsProvider the private key operations provider, or nullptr if
+   * no provider can be used with the context configuration.
+   */
+  virtual PrivateKeyOperationsProviderSharedPtr
+  createPrivateKeyOperationsProvider(const envoy::api::v2::auth::PrivateKeyMethod& message,
+                                     Envoy::Server::Configuration::TransportSocketFactoryContext&
+                                         private_key_provider_context) PURE;
+};
+
+} // namespace Ssl
+} // namespace Envoy

include/envoy/ssl/private_key/private_key_callbacks.h

@@ -0,0 +1,30 @@
+#pragma once
+
+#include <functional>
+#include <string>
+
+#include "envoy/common/pure.h"
+
+namespace Envoy {
+namespace Ssl {
+
+enum class PrivateKeyOperationStatus {
+  Success,
+  Failure,
+};
+
+class PrivateKeyOperationsCallbacks {
+public:
+  virtual ~PrivateKeyOperationsCallbacks() {}
+
+  /**
+   * Callback function which is called when the asynchronous private key
+   * operation has been completed.
+   * @param status is "Success" or "Failure" depending on whether the private key operation was
+   * successful or not.
+   */
+  virtual void complete(PrivateKeyOperationStatus status) PURE;
+};
+
+} // namespace Ssl
+} // namespace Envoy

include/envoy/ssl/private_key/private_key_config.h

@@ -0,0 +1,22 @@
+#pragma once
+
+#include "envoy/api/v2/auth/cert.pb.h"
+#include "envoy/registry/registry.h"
+#include "envoy/ssl/private_key/private_key.h"
+
+namespace Envoy {
+namespace Ssl {
+
+// Base class which the private key operation provider implementations can register.
+
+class PrivateKeyOperationsProviderInstanceFactory {
+public:
+  virtual ~PrivateKeyOperationsProviderInstanceFactory() {}
+  virtual PrivateKeyOperationsProviderSharedPtr createPrivateKeyOperationsProviderInstance(
+      const envoy::api::v2::auth::PrivateKeyMethod& message,
+      Server::Configuration::TransportSocketFactoryContext& private_key_provider_context) PURE;
+  virtual std::string name() const PURE;
+};
+
+} // namespace Ssl
+} // namespace Envoy

include/envoy/ssl/tls_certificate_config.h

@@ -4,6 +4,7 @@
 #include <string>
 
 #include "envoy/common/pure.h"
+#include "envoy/ssl/private_key/private_key.h"
 
 namespace Envoy {
 namespace Ssl {
@@ -34,6 +35,11 @@ class TlsCertificateConfig {
    */
   virtual const std::string& privateKeyPath() const PURE;
 
+  /**
+   * @return private key method provider.
+   */
+  virtual Envoy::Ssl::PrivateKeyOperationsProviderSharedPtr privateKeyMethod() const PURE;
+
   /**
    * @return a string of password.
    */

source/common/ssl/BUILD

@@ -13,7 +13,9 @@ envoy_cc_library(
     srcs = ["tls_certificate_config_impl.cc"],
     hdrs = ["tls_certificate_config_impl.h"],
     deps = [
+        "//include/envoy/server:transport_socket_config_interface",
         "//include/envoy/ssl:tls_certificate_config_interface",
+        "//include/envoy/ssl/private_key:private_key_interface",
         "//source/common/common:empty_string",
         "//source/common/config:datasource_lib",
         "@envoy_api//envoy/api/v2/auth:cert_cc",

source/common/ssl/tls_certificate_config_impl.cc

@@ -1,6 +1,7 @@
 #include "common/ssl/tls_certificate_config_impl.h"
 
 #include "envoy/common/exception.h"
+#include "envoy/server/transport_socket_config.h"
 
 #include "common/common/empty_string.h"
 #include "common/common/fmt.h"
@@ -22,9 +23,33 @@ TlsCertificateConfigImpl::TlsCertificateConfigImpl(
                             .value_or(private_key_.empty() ? EMPTY_STRING : INLINE_STRING)),
       password_(Config::DataSource::read(config.password(), true, api)),
       password_path_(Config::DataSource::getPath(config.password())
-                         .value_or(password_.empty() ? EMPTY_STRING : INLINE_STRING)) {
+                         .value_or(password_.empty() ? EMPTY_STRING : INLINE_STRING)) {}
 
-  if (certificate_chain_.empty() || private_key_.empty()) {
+TlsCertificateConfigImpl::TlsCertificateConfigImpl(
+    const envoy::api::v2::auth::TlsCertificate& config, Api::Api& api,
+    bool expect_private_key_method)
+    : TlsCertificateConfigImpl(config, api) {
+  {
+    if (!expect_private_key_method) {
+      if (certificate_chain_.empty() || private_key_.empty()) {
+        throw EnvoyException(fmt::format("Failed to load incomplete certificate from {}, {}",
+                                         certificate_chain_path_, private_key_path_));
+      }
+    }
+  }
+}
+
+TlsCertificateConfigImpl::TlsCertificateConfigImpl(
+    const envoy::api::v2::auth::TlsCertificate& config,
+    Server::Configuration::TransportSocketFactoryContext& factory_context, Api::Api& api)
+    : TlsCertificateConfigImpl(config, api, true) {
+  if (config.has_private_key_method()) {
+    private_key_method_ =
+        factory_context.sslContextManager()
+            .privateKeyOperationsManager()
+            .createPrivateKeyOperationsProvider(config.private_key_method(), factory_context);
+  }
+  if (certificate_chain_.empty() || (private_key_.empty() && private_key_method_ == nullptr)) {
     throw EnvoyException(fmt::format("Failed to load incomplete certificate from {}, {}",
                                      certificate_chain_path_, private_key_path_));
   }

source/common/ssl/tls_certificate_config_impl.h

@@ -4,27 +4,37 @@
 
 #include "envoy/api/api.h"
 #include "envoy/api/v2/auth/cert.pb.h"
+#include "envoy/ssl/private_key/private_key.h"
 #include "envoy/ssl/tls_certificate_config.h"
 
 namespace Envoy {
 namespace Ssl {
 
 class TlsCertificateConfigImpl : public TlsCertificateConfig {
 public:
-  TlsCertificateConfigImpl(const envoy::api::v2::auth::TlsCertificate& config, Api::Api& api);
+  TlsCertificateConfigImpl(const envoy::api::v2::auth::TlsCertificate& config, Api::Api& api,
+                           bool expect_private_key_method);
+  TlsCertificateConfigImpl(const envoy::api::v2::auth::TlsCertificate& config,
+                           Server::Configuration::TransportSocketFactoryContext& factory_context,
+                           Api::Api& api);
 
   const std::string& certificateChain() const override { return certificate_chain_; }
   const std::string& certificateChainPath() const override { return certificate_chain_path_; }
   const std::string& privateKey() const override { return private_key_; }
   const std::string& privateKeyPath() const override { return private_key_path_; }
+  Envoy::Ssl::PrivateKeyOperationsProviderSharedPtr privateKeyMethod() const override {
+    return private_key_method_;
+  }
   const std::string& password() const override { return password_; }
   const std::string& passwordPath() const override { return password_path_; }
 
 private:
+  TlsCertificateConfigImpl(const envoy::api::v2::auth::TlsCertificate& config, Api::Api& api);
   const std::string certificate_chain_;
   const std::string certificate_chain_path_;
   const std::string private_key_;
   const std::string private_key_path_;
+  Envoy::Ssl::PrivateKeyOperationsProviderSharedPtr private_key_method_{};
   const std::string password_;
   const std::string password_path_;
 };

source/extensions/transport_sockets/tls/BUILD

@@ -38,6 +38,8 @@ envoy_cc_library(
         ":utility_lib",
         "//include/envoy/network:connection_interface",
         "//include/envoy/network:transport_socket_interface",
+        "//include/envoy/ssl/private_key:private_key_callbacks_interface",
+        "//include/envoy/ssl/private_key:private_key_interface",
         "//include/envoy/stats:stats_macros",
         "//source/common/common:assert_lib",
         "//source/common/common:empty_string",
@@ -91,13 +93,15 @@ envoy_cc_library(
         "//include/envoy/ssl:context_config_interface",
         "//include/envoy/ssl:context_interface",
         "//include/envoy/ssl:context_manager_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/protobuf:utility_lib",
+        "//source/extensions/transport_sockets/tls/private_key:private_key_manager_lib",
         "@envoy_api//envoy/admin/v2alpha:certs_cc",
     ],
 )