tls: add support for verify_certificate_spki. (envoyproxy#3475)

Signed-off-by: Piotr Sikora <[email protected]>

Author: PiotrSikora

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

@@ -127,6 +127,39 @@ message CertificateValidationContext {
   // system CA locations.
   core.DataSource trusted_ca = 1;
 
+  // An optional list of base64-encoded SHA-256 hashes. If specified, Envoy will verify that the
+  // SHA-256 of the DER-encoded Subject Public Key Information (SPKI) of the presented certificate
+  // matches one of the specified values.
+  //
+  // A base64-encoded SHA-256 of the Subject Public Key Information (SPKI) of the certificate
+  // can be generated with the following command:
+  //
+  // .. code-block:: bash
+  //
+  //   $ openssl x509 -in path/to/client.crt -noout -pubkey \
+  //     | openssl pkey -pubin -outform DER \
+  //     | openssl dgst -sha256 -binary \
+  //     | openssl enc -base64
+  //   NvqYIYSbgK2vCJpQhObf77vv+bQWtc5ek5RIOwPiC9A=
+  //
+  // This is the format used in HTTP Public Key Pinning.
+  //
+  // When both:
+  // :ref:`verify_certificate_hash
+  // <envoy_api_field_auth.CertificateValidationContext.verify_certificate_hash>` and
+  // :ref:`verify_certificate_spki
+  // <envoy_api_field_auth.CertificateValidationContext.verify_certificate_spki>` are specified,
+  // a hash matching value from either of the lists will result in the certificate being accepted.
+  //
+  // .. attention::
+  //
+  //   This option is preferred over :ref:`verify_certificate_hash
+  //   <envoy_api_field_auth.CertificateValidationContext.verify_certificate_hash>`,
+  //   because SPKI is tied to a private key, so it doesn't change when the certificate
+  //   is renewed using the same private key.
+  repeated string verify_certificate_spki = 3
+      [(validate.rules).repeated .items.string = {min_bytes: 44, max_bytes: 44}];
+
   // An optional list of hex-encoded SHA-256 hashes. If specified, Envoy will verify that
   // the SHA-256 of the DER-encoded presented certificate matches one of the specified values.
   //
@@ -146,15 +179,16 @@ message CertificateValidationContext {
   //   DF:6F:F7:2F:E9:11:65:21:26:8F:6F:2D:D4:96:6F:51:DF:47:98:83:FE:70:37:B3:9F:75:91:6A:C3:04:9D:1A
   //
   // Both of those formats are acceptable.
+  //
+  // When both:
+  // :ref:`verify_certificate_hash
+  // <envoy_api_field_auth.CertificateValidationContext.verify_certificate_hash>` and
+  // :ref:`verify_certificate_spki
+  // <envoy_api_field_auth.CertificateValidationContext.verify_certificate_spki>` are specified,
+  // a hash matching value from either of the lists will result in the certificate being accepted.
   repeated string verify_certificate_hash = 2
       [(validate.rules).repeated .items.string = {min_bytes: 64, max_bytes: 95}];
 
-  // If specified, Envoy will verify (pin) base64-encoded SHA-256 hash of
-  // the Subject Public Key Information (SPKI) of the presented certificate.
-  // This is the same format as used in HTTP Public Key Pinning.
-  // [#not-implemented-hide:]
-  repeated string verify_spki_sha256 = 3;
-
   // An optional list of Subject Alternative Names. If specified, Envoy will verify that the
   // Subject Alternative Name of the presented certificate matches one of the specified values.
   repeated string verify_subject_alt_name = 4;

docs/root/intro/version_history.rst

@@ -110,6 +110,8 @@ Version history
 * stats: added support for histograms.
 * stats: added :ref:`option to configure the statsd prefix<envoy_api_field_config.metrics.v2.StatsdSink.prefix>`
 * stats: updated stats sink interface to flush through a single call.
+* tls: added support for
+  :ref:`verify_certificate_spki <envoy_api_field_auth.CertificateValidationContext.verify_certificate_spki>`.
 * tls: added support for multiple
   :ref:`verify_certificate_hash <envoy_api_field_auth.CertificateValidationContext.verify_certificate_hash>`
   values.

include/envoy/ssl/context_config.h

@@ -92,6 +92,11 @@ class ContextConfig {
    */
   virtual const std::vector<std::string>& verifyCertificateHashList() const PURE;
 
+  /**
+   * @return A list of a hex-encoded SHA-256 SPKI hashes to be verified.
+   */
+  virtual const std::vector<std::string>& verifyCertificateSpkiList() const PURE;
+
   /**
    * @return The minimum TLS protocol version to negotiate.
    */

source/common/ssl/BUILD

@@ -62,6 +62,7 @@ envoy_cc_library(
         "//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/ssl/context_config_impl.cc

@@ -61,6 +61,8 @@ ContextConfigImpl::ContextConfigImpl(const envoy::api::v2::auth::CommonTlsContex
                                     config.validation_context().verify_subject_alt_name().end()),
       verify_certificate_hash_list_(config.validation_context().verify_certificate_hash().begin(),
                                     config.validation_context().verify_certificate_hash().end()),
+      verify_certificate_spki_list_(config.validation_context().verify_certificate_spki().begin(),
+                                    config.validation_context().verify_certificate_spki().end()),
       min_protocol_version_(
           tlsVersionFromProto(config.tls_params().tls_minimum_protocol_version(), TLS1_VERSION)),
       max_protocol_version_(

source/common/ssl/context_config_impl.h

@@ -46,6 +46,9 @@ class ContextConfigImpl : public virtual Ssl::ContextConfig {
   const std::vector<std::string>& verifyCertificateHashList() const override {
     return verify_certificate_hash_list_;
   };
+  const std::vector<std::string>& verifyCertificateSpkiList() const override {
+    return verify_certificate_spki_list_;
+  };
   unsigned minProtocolVersion() const override { return min_protocol_version_; };
   unsigned maxProtocolVersion() const override { return max_protocol_version_; };
 
@@ -74,6 +77,7 @@ class ContextConfigImpl : public virtual Ssl::ContextConfig {
   const std::string private_key_path_;
   const std::vector<std::string> verify_subject_alt_name_list_;
   const std::vector<std::string> verify_certificate_hash_list_;
+  const std::vector<std::string> verify_certificate_spki_list_;
   const unsigned min_protocol_version_;
   const unsigned max_protocol_version_;
 };

source/common/ssl/context_impl.cc

@@ -9,6 +9,7 @@
 #include "envoy/runtime/runtime.h"
 
 #include "common/common/assert.h"
+#include "common/common/base64.h"
 #include "common/common/fmt.h"
 #include "common/common/hex.h"
 
@@ -131,6 +132,17 @@ ContextImpl::ContextImpl(ContextManagerImpl& parent, Stats::Scope& scope,
     verify_mode = SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT;
   }
 
+  if (!config.verifyCertificateSpkiList().empty()) {
+    for (auto hash : config.verifyCertificateSpkiList()) {
+      const auto decoded = Base64::decode(hash);
+      if (decoded.size() != SHA256_DIGEST_LENGTH) {
+        throw EnvoyException(fmt::format("Invalid base64-encoded SHA-256 {}", hash));
+      }
+      verify_certificate_spki_list_.emplace_back(decoded.begin(), decoded.end());
+    }
+    verify_mode = SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT;
+  }
+
   if (verify_mode != SSL_VERIFY_NONE) {
     SSL_CTX_set_verify(ctx_.get(), verify_mode, nullptr);
     SSL_CTX_set_cert_verify_callback(ctx_.get(), ContextImpl::verifyCallback, this);
@@ -263,10 +275,18 @@ int ContextImpl::verifyCertificate(X509* cert) {
     return 0;
   }
 
-  if (!verify_certificate_hash_list_.empty() &&
-      !verifyCertificateHashList(cert, verify_certificate_hash_list_)) {
-    stats_.fail_verify_cert_hash_.inc();
-    return 0;
+  if (!verify_certificate_hash_list_.empty() || !verify_certificate_spki_list_.empty()) {
+    const bool valid_certificate_hash =
+        !verify_certificate_hash_list_.empty() &&
+        verifyCertificateHashList(cert, verify_certificate_hash_list_);
+    const bool valid_certificate_spki =
+        !verify_certificate_spki_list_.empty() &&
+        verifyCertificateSpkiList(cert, verify_certificate_spki_list_);
+
+    if (!valid_certificate_hash && !valid_certificate_spki) {
+      stats_.fail_verify_cert_hash_.inc();
+      return 0;
+    }
   }
 
   return 1;
@@ -334,13 +354,37 @@ bool ContextImpl::dNSNameMatch(const std::string& dNSName, const char* pattern)
 }
 
 bool ContextImpl::verifyCertificateHashList(
-    X509* cert, const std::vector<std::vector<uint8_t>>& certificate_hash_list) {
+    X509* cert, const std::vector<std::vector<uint8_t>>& expected_hashes) {
   std::vector<uint8_t> computed_hash(SHA256_DIGEST_LENGTH);
   unsigned int n;
   X509_digest(cert, EVP_sha256(), computed_hash.data(), &n);
   RELEASE_ASSERT(n == computed_hash.size());
 
-  for (const auto& expected_hash : certificate_hash_list) {
+  for (const auto& expected_hash : expected_hashes) {
+    if (computed_hash == expected_hash) {
+      return true;
+    }
+  }
+  return false;
+}
+
+bool ContextImpl::verifyCertificateSpkiList(
+    X509* cert, const std::vector<std::vector<uint8_t>>& expected_hashes) {
+  X509_PUBKEY* pubkey = X509_get_X509_PUBKEY(cert);
+  if (pubkey == nullptr) {
+    return false;
+  }
+  uint8_t* spki = nullptr;
+  const int len = i2d_X509_PUBKEY(pubkey, &spki);
+  if (len < 0) {
+    return false;
+  }
+  bssl::UniquePtr<uint8_t> free_spki(spki);
+
+  std::vector<uint8_t> computed_hash(SHA256_DIGEST_LENGTH);
+  SHA256(spki, len, computed_hash.data());
+
+  for (const auto& expected_hash : expected_hashes) {
     if (computed_hash == expected_hash) {
       return true;
     }
@@ -579,6 +623,14 @@ ServerContextImpl::ServerContextImpl(ContextManagerImpl& parent, Stats::Scope& s
                                 sizeof(std::remove_reference<decltype(hash)>::type::value_type));
       RELEASE_ASSERT(rc == 1);
     }
+
+    // verify_certificate_spki_ can only be set with a ca_cert
+    for (const auto& hash : verify_certificate_spki_list_) {
+      rc = EVP_DigestUpdate(&md, hash.data(),
+                            hash.size() *
+                                sizeof(std::remove_reference<decltype(hash)>::type::value_type));
+      RELEASE_ASSERT(rc == 1);
+    }
   }
 
   // Hash configured SNIs for this context, so that sessions cannot be resumed across different

source/common/ssl/context_impl.h

@@ -92,12 +92,22 @@ class ContextImpl : public virtual Context {
    * certificate.
    *
    * @param ssl the certificate to verify
-   * @param certificate_hash_list the configured list of certificate hashes to match
+   * @param expected_hashes the configured list of certificate hashes to match
    * @return true if the verification succeeds
    */
-  static bool
-  verifyCertificateHashList(X509* cert,
-                            const std::vector<std::vector<uint8_t>>& certificate_hash_list);
+  static bool verifyCertificateHashList(X509* cert,
+                                        const std::vector<std::vector<uint8_t>>& expected_hashes);
+
+  /**
+   * Verifies certificate hash for pinning. The hash is a base64-encoded SHA-256 of the DER-encoded
+   * Subject Public Key Information (SPKI) of the certificate.
+   *
+   * @param ssl the certificate to verify
+   * @param expected_hashes the configured list of certificate hashes to match
+   * @return true if the verification succeeds
+   */
+  static bool verifyCertificateSpkiList(X509* cert,
+                                        const std::vector<std::vector<uint8_t>>& expected_hashes);
 
   std::vector<uint8_t> parseAlpnProtocols(const std::string& alpn_protocols);
   static SslStats generateStats(Stats::Scope& scope);
@@ -110,6 +120,7 @@ class ContextImpl : public virtual Context {
   bssl::UniquePtr<SSL_CTX> ctx_;
   std::vector<std::string> verify_subject_alt_name_list_;
   std::vector<std::vector<uint8_t>> verify_certificate_hash_list_;
+  std::vector<std::vector<uint8_t>> verify_certificate_spki_list_;
   Stats::Scope& scope_;
   SslStats stats_;
   std::vector<uint8_t> parsed_alpn_protocols_;

test/common/ssl/context_impl_test.cc

@@ -359,6 +359,21 @@ TEST(ClientContextConfigImplTest, InvalidCertificateHash) {
                           EnvoyException, "Invalid hex-encoded SHA-256 .*");
 }
 
+// Validate that values other than a base64-encoded SHA-256 fail config validation.
+TEST(ClientContextConfigImplTest, InvalidCertificateSpki) {
+  envoy::api::v2::auth::UpstreamTlsContext tls_context;
+  tls_context.mutable_common_tls_context()
+      ->mutable_validation_context()
+      // Not a base64-encoded string.
+      ->add_verify_certificate_spki("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
+  ClientContextConfigImpl client_context_config(tls_context);
+  Runtime::MockLoader runtime;
+  ContextManagerImpl manager(runtime);
+  Stats::IsolatedStoreImpl store;
+  EXPECT_THROW_WITH_REGEX(manager.createSslClientContext(store, client_context_config),
+                          EnvoyException, "Invalid base64-encoded SHA-256 .*");
+}
+
 // Multiple TLS certificates are not yet supported.
 // TODO(PiotrSikora): Support multiple TLS certificates.
 TEST(ClientContextConfigImplTest, MultipleTlsCertificates) {