tls: support BoringSSL private key async functionality

CODEOWNERS

@@ -26,6 +26,8 @@ extensions/filters/common/original_src @snowp @klarose
 /*/extensions/filters/http/header_to_metadata @rgs1 @zuercher
 # alts transport socket extension
 /*/extensions/transport_sockets/alts @htuch @yangminzhu
+# tls transport socket extension
+/*/extensions/transport_sockets/tls @PiotrSikora @lizan
 # sni_cluster extension
 /*/extensions/filters/network/sni_cluster @rshriram @lizan
 # tracers.datadog extension

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,13 +104,38 @@ message TlsParameters {
   repeated string ecdh_curves = 4;
 }
 
+// BoringSSL private key method configuration. The private key methods are used for external
+// (potentially asynchronous) signing and decryption operations. Some use cases for private key
+// methods would be TPM support and TLS acceleration.
+message PrivateKeyProvider {
+  // Private key method provider name. The name must match a
+  // supported private key method provider type.
+  string provider_name = 1 [(validate.rules).string.min_bytes = 1];
+
+  // Private key method provider specific configuration.
+  oneof config_type {
+    google.protobuf.Struct config = 2;
+
+    google.protobuf.Any typed_config = 3;
+  }
+}
+
 message TlsCertificate {
   // The TLS certificate chain.
   core.DataSource certificate_chain = 1;
 
   // The TLS private key.
   core.DataSource private_key = 2;
 
+  // BoringSSL private key method provider. This is an alternative to :ref:`private_key
+  // <envoy_api_field_auth.TlsCertificate.private_key>` field. This can't be
+  // marked as ``oneof`` due to API compatibility reasons. Setting both :ref:`private_key
+  // <envoy_api_field_auth.TlsCertificate.private_key>` and
+  // :ref:`private_key_provider
+  // <envoy_api_field_auth.TlsCertificate.private_key_provider>` fields will result in an
+  // error.
+  PrivateKeyProvider private_key_provider = 6;
+
   // The password to decrypt the TLS private key. If this field is not set, it is assumed that the
   // TLS private key is not password encrypted.
   core.DataSource password = 3;

docs/root/extending/extending.rst

@@ -19,6 +19,7 @@ types including:
 * :ref:`Stat sinks <arch_overview_statistics>`
 * :ref:`Tracers <arch_overview_tracing>`
 * Transport sockets
+* BoringSSL private key methods
 
 As of this writing there is no high level extension developer documentation. The
 :repo:`existing extensions <source/extensions>` are a good way to learn what is possible.

docs/root/intro/arch_overview/security/ssl.rst

@@ -23,6 +23,10 @@ requirements (TLS1.2, SNI, etc.). Envoy supports the following TLS features:
   tickets (see `RFC 5077 <https://www.ietf.org/rfc/rfc5077.txt>`_). Resumption can be performed
   across hot restarts and between parallel Envoy instances (typically useful in a front proxy
   configuration).
+* **BoringSSL private key methods**: TLS private key operations (signing and decrypting) can be
+  performed asynchronously from an extension. This allows extending Envoy to support various key
+  management schemes (such as TPM) and TLS acceleration. This mechanism uses
+  `BoringSSL private key method interface <https://github.com/google/boringssl/blob/c0b4c72b6d4c6f4828a373ec454bd646390017d4/include/openssl/ssl.h#L1169>`_.
 
 Underlying implementation
 -------------------------

include/envoy/ssl/BUILD

@@ -48,6 +48,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

@@ -5,6 +5,7 @@
 #include "envoy/common/time.h"
 #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 {
@@ -39,6 +40,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 PrivateKeyMethodManager& privateKeyMethodManager() PURE;
 };
 
 using ContextManagerPtr = std::unique_ptr<ContextManager>;

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,85 @@
+#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 {
+
+using BoringSslPrivateKeyMethodSharedPtr = std::shared_ptr<SSL_PRIVATE_KEY_METHOD>;
+
+class PrivateKeyMethodProvider {
+public:
+  virtual ~PrivateKeyMethodProvider() = default;
+
+  /**
+   * Register an SSL connection to private key operations by the provider.
+   * @param ssl a SSL connection object.
+   * @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.
+   */
+  virtual void registerPrivateKeyMethod(SSL* ssl, PrivateKeyConnectionCallbacks& cb,
+                                        Event::Dispatcher& dispatcher) PURE;
+
+  /**
+   * Unregister an SSL connection from private key operations by the provider.
+   * @param ssl a SSL connection object.
+   * @throw EnvoyException if registration fails.
+   */
+  virtual void unregisterPrivateKeyMethod(SSL* ssl) PURE;
+
+  /**
+   * Check whether the private key method satisfies FIPS requirements.
+   * @return true if FIPS key requirements are satisfied, false if not.
+   */
+  virtual bool checkFips() PURE;
+
+  /**
+   * Get the private key methods from the provider.
+   * @return the private key methods associated with this provider and
+   * configuration.
+   */
+  virtual BoringSslPrivateKeyMethodSharedPtr getBoringSslPrivateKeyMethod() PURE;
+};
+
+using PrivateKeyMethodProviderSharedPtr = std::shared_ptr<PrivateKeyMethodProvider>;
+
+/**
+ * A manager for finding correct user-provided functions for handling BoringSSL private key
+ * operations.
+ */
+class PrivateKeyMethodManager {
+public:
+  virtual ~PrivateKeyMethodManager() = default;
+
+  /**
+   * Finds and returns a private key operations provider for BoringSSL.
+   *
+   * @param config a protobuf message object containing a PrivateKeyProvider message.
+   * @param factory_context context that provides components for creating and
+   * initializing connections using asynchronous private key operations.
+   * @return PrivateKeyMethodProvider the private key operations provider, or nullptr if
+   * no provider can be used with the context configuration.
+   */
+  virtual PrivateKeyMethodProviderSharedPtr createPrivateKeyMethodProvider(
+      const envoy::api::v2::auth::PrivateKeyProvider& config,
+      Envoy::Server::Configuration::TransportSocketFactoryContext& factory_context) PURE;
+};
+
+} // namespace Ssl
+} // namespace Envoy

include/envoy/ssl/private_key/private_key_callbacks.h

@@ -0,0 +1,25 @@
+#pragma once
+
+#include <functional>
+#include <string>
+
+#include "envoy/common/pure.h"
+
+namespace Envoy {
+namespace Ssl {
+
+class PrivateKeyConnectionCallbacks {
+public:
+  virtual ~PrivateKeyConnectionCallbacks() = default;
+
+  /**
+   * Callback function which is called when the asynchronous private key
+   * operation has been completed (with either success or failure). The
+   * provider will communicate the success status when SSL_do_handshake()
+   * is called the next time.
+   */
+  virtual void onPrivateKeyMethodComplete() 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 PrivateKeyMethodProviderInstanceFactory {
+public:
+  virtual ~PrivateKeyMethodProviderInstanceFactory() = default;
+  virtual PrivateKeyMethodProviderSharedPtr createPrivateKeyMethodProviderInstance(
+      const envoy::api::v2::auth::PrivateKeyProvider& config,
+      Server::Configuration::TransportSocketFactoryContext& factory_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::PrivateKeyMethodProviderSharedPtr 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"
@@ -12,7 +13,8 @@ namespace Ssl {
 static const std::string INLINE_STRING = "<inline>";
 
 TlsCertificateConfigImpl::TlsCertificateConfigImpl(
-    const envoy::api::v2::auth::TlsCertificate& config, Api::Api& api)
+    const envoy::api::v2::auth::TlsCertificate& config,
+    Server::Configuration::TransportSocketFactoryContext* factory_context, Api::Api& api)
     : certificate_chain_(Config::DataSource::read(config.certificate_chain(), true, api)),
       certificate_chain_path_(
           Config::DataSource::getPath(config.certificate_chain())
@@ -22,9 +24,18 @@ 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)) {
-
-  if (certificate_chain_.empty() || private_key_.empty()) {
+                         .value_or(password_.empty() ? EMPTY_STRING : INLINE_STRING)),
+      private_key_method_(
+          factory_context != nullptr && config.has_private_key_provider()
+              ? factory_context->sslContextManager()
+                    .privateKeyMethodManager()
+                    .createPrivateKeyMethodProvider(config.private_key_provider(), *factory_context)
+              : nullptr) {
+  if (config.has_private_key_provider() && config.has_private_key()) {
+    throw EnvoyException(fmt::format(
+        "Certificate configuration can't have both private_key and private_key_provider"));
+  }
+  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,21 +4,27 @@
 
 #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,
+                           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_; }
   const std::string& password() const override { return password_; }
   const std::string& passwordPath() const override { return password_path_; }
+  Envoy::Ssl::PrivateKeyMethodProviderSharedPtr privateKeyMethod() const override {
+    return private_key_method_;
+  }
 
 private:
   const std::string certificate_chain_;
@@ -27,6 +33,7 @@ class TlsCertificateConfigImpl : public TlsCertificateConfig {
   const std::string private_key_path_;
   const std::string password_;
   const std::string password_path_;
+  Envoy::Ssl::PrivateKeyMethodProviderSharedPtr private_key_method_{};
 };
 
 } // namespace Ssl