string matcher: add optional context (#38924)

Adding an optional parameter to string matcher
API to support use cases where the matching can be backed with
per-stream context. A use case for example is described in #38862.

Fixes #38862

Signed-off-by: Ohad Vano <[email protected]>

Author: ohadvano

changelogs/current.yaml

@@ -35,6 +35,10 @@ minor_behavior_changes:
     AWS request signing and AWS Lambda extensions will now no longer return empty credentials (and fail to sign) when
     credentials are still pending from the async credential providers. If all providers are unable to retrieve credentials
     then the original behaviour with a signing failure will occur.
+- area: string_matcher
+  change: |
+    The string matcher API extended with another method that allows passing a context for the matching operation.
+    The initial supporting use case is passing ``StreamInfo`` in the context when performing SAN matching.
 - area: formatter
   change: |
     The formatter ``%CEL%`` and ``%METADATA%`` will be treated as built-in formatters and could be used directly in the

contrib/hyperscan/matching/input_matchers/source/matcher.h

@@ -39,6 +39,7 @@ class Matcher : public Envoy::Regex::CompiledMatcher, public Envoy::Matcher::Inp
 
   // Envoy::Regex::CompiledMatcher
   bool match(absl::string_view value) const override;
+  bool match(absl::string_view value, const Context&) const override { return match(value); }
   std::string replaceAll(absl::string_view value, absl::string_view substitution) const override;
 
   // Envoy::Matcher::InputMatcher

envoy/common/BUILD

@@ -77,6 +77,10 @@ envoy_cc_library(
 envoy_cc_library(
     name = "matchers_interface",
     hdrs = ["matchers.h"],
+    deps = [
+        ":optref_lib",
+        "//envoy/stream_info:stream_info_interface",
+    ],
 )
 
 envoy_cc_library(

envoy/common/matchers.h

@@ -2,7 +2,9 @@
 
 #include <memory>
 
+#include "envoy/common/optref.h"
 #include "envoy/common/pure.h"
+#include "envoy/stream_info/stream_info.h"
 
 #include "absl/strings/string_view.h"
 
@@ -16,10 +18,20 @@ class StringMatcher {
 public:
   virtual ~StringMatcher() = default;
 
+  struct Context {
+    OptRef<const StreamInfo::StreamInfo> stream_info_;
+  };
+
   /**
    * Return whether a passed string value matches.
    */
   virtual bool match(const absl::string_view value) const PURE;
+
+  /**
+   * Return whether a passed string value matches with context.
+   * Because most implementations don't use the context, provides a default implementation.
+   */
+  virtual bool match(const absl::string_view value, const Context&) const { return match(value); }
 };
 
 using StringMatcherPtr = std::unique_ptr<const StringMatcher>;

source/common/common/matchers.h

@@ -98,7 +98,7 @@ class ExactStringMatcher {
       : exact_(exact), ignore_case_(ignore_case) {}
 
   // StringMatcher
-  bool match(const absl::string_view value) const {
+  bool match(const absl::string_view value, OptRef<const StringMatcher::Context>) const {
     return ignore_case_ ? absl::EqualsIgnoreCase(value, exact_) : value == exact_;
   }
 
@@ -116,7 +116,7 @@ class PrefixStringMatcher {
       : prefix_(prefix), ignore_case_(ignore_case) {}
 
   // StringMatcher
-  bool match(const absl::string_view value) const {
+  bool match(const absl::string_view value, OptRef<const StringMatcher::Context>) const {
     return ignore_case_ ? absl::StartsWithIgnoreCase(value, prefix_)
                         : absl::StartsWith(value, prefix_);
   }
@@ -136,7 +136,7 @@ class SuffixStringMatcher {
       : suffix_(suffix), ignore_case_(ignore_case) {}
 
   // StringMatcher
-  bool match(const absl::string_view value) const {
+  bool match(const absl::string_view value, OptRef<const StringMatcher::Context>) const {
     return ignore_case_ ? absl::EndsWithIgnoreCase(value, suffix_) : absl::EndsWith(value, suffix_);
   }
 
@@ -161,7 +161,9 @@ class RegexStringMatcher {
   RegexStringMatcher(RegexStringMatcher&& other) noexcept { regex_ = std::move(other.regex_); }
 
   // StringMatcher
-  bool match(const absl::string_view value) const { return regex_->match(value); }
+  bool match(const absl::string_view value, OptRef<const StringMatcher::Context>) const {
+    return regex_->match(value);
+  }
 
   const std::string& stringRepresentation() const { return regex_->pattern(); }
 
@@ -177,7 +179,7 @@ class ContainsStringMatcher {
         ignore_case_(ignore_case) {}
 
   // StringMatcher
-  bool match(const absl::string_view value) const {
+  bool match(const absl::string_view value, OptRef<const StringMatcher::Context>) const {
     return ignore_case_ ? absl::StrContains(absl::AsciiStrToLower(value), contents_)
                         : absl::StrContains(value, contents_);
   }
@@ -204,7 +206,13 @@ class CustomStringMatcher {
       : custom_(getExtensionStringMatcher(custom, context)) {}
 
   // StringMatcher
-  bool match(const absl::string_view value) const { return custom_->match(value); }
+  bool match(const absl::string_view value, OptRef<const StringMatcher::Context> context) const {
+    if (context) {
+      return custom_->match(value, context.ref());
+    }
+
+    return custom_->match(value);
+  }
 
   const std::string& stringRepresentation() const { return EMPTY_STRING; }
 
@@ -232,11 +240,9 @@ class StringMatcherImpl : public ValueMatcher, public StringMatcher {
   }
 
   // StringMatcher
-  bool match(const absl::string_view value) const override {
-    // Implementing polymorphism for match(absl::string_value) on the different
-    // types that can be in the matcher_ variant.
-    auto call_match = [value](const auto& obj) -> bool { return obj.match(value); };
-    return absl::visit(call_match, matcher_);
+  bool match(const absl::string_view value) const override { return doMatch(value, absl::nullopt); }
+  bool match(const absl::string_view value, const StringMatcher::Context& context) const override {
+    return doMatch(value, makeOptRef(context));
   }
 
   // ValueMatcher
@@ -311,6 +317,16 @@ class StringMatcherImpl : public ValueMatcher, public StringMatcher {
     }
   }
 
+  bool doMatch(const absl::string_view value, OptRef<const StringMatcher::Context> context) const {
+    // Implementing polymorphism for match(absl::string_value) on the different
+    // types that can be in the matcher_ variant.
+    auto call_match = [value, context](const auto& obj) -> bool {
+      return obj.match(value, context);
+    };
+
+    return absl::visit(call_match, matcher_);
+  }
+
   StringMatcherVariant matcher_;
 };
 

source/common/tls/cert_validator/default_validator.cc

@@ -203,6 +203,7 @@ absl::StatusOr<int> DefaultCertValidator::initializeSslContexts(std::vector<SSL_
 bool DefaultCertValidator::verifyCertAndUpdateStatus(
     X509* leaf_cert, absl::string_view sni,
     const Network::TransportSocketOptions* transport_socket_options,
+    const CertValidator::ExtraValidationContext& validation_context,
     Envoy::Ssl::ClientValidationStatus& detailed_status, std::string* error_details,
     uint8_t* out_alert) {
 
@@ -218,9 +219,13 @@ bool DefaultCertValidator::verifyCertAndUpdateStatus(
     match_sni_san.emplace_back(std::make_unique<DnsExactStringSanMatcher>(sni));
     match_san_override = match_sni_san;
   }
-  Envoy::Ssl::ClientValidationStatus validated = verifyCertificate(
-      leaf_cert, verify_san_override.value_or(std::vector<std::string>()),
-      match_san_override.value_or(subject_alt_name_matchers_), error_details, out_alert);
+  Envoy::Ssl::ClientValidationStatus validated =
+      verifyCertificate(leaf_cert, verify_san_override.value_or(std::vector<std::string>()),
+                        match_san_override.value_or(subject_alt_name_matchers_),
+                        validation_context.callbacks != nullptr
+                            ? makeOptRef(validation_context.callbacks->connection().streamInfo())
+                            : absl::nullopt,
+                        error_details, out_alert);
 
   if (detailed_status == Envoy::Ssl::ClientValidationStatus::NotValidated ||
       validated != Envoy::Ssl::ClientValidationStatus::NotValidated) {
@@ -241,6 +246,7 @@ bool DefaultCertValidator::verifyCertAndUpdateStatus(
 Envoy::Ssl::ClientValidationStatus
 DefaultCertValidator::verifyCertificate(X509* cert, const std::vector<std::string>& verify_san_list,
                                         const std::vector<SanMatcherPtr>& subject_alt_name_matchers,
+                                        OptRef<const StreamInfo::StreamInfo> stream_info,
                                         std::string* error_details, uint8_t* out_alert) {
   Envoy::Ssl::ClientValidationStatus validated = Envoy::Ssl::ClientValidationStatus::NotValidated;
   if (!verify_san_list.empty()) {
@@ -257,7 +263,7 @@ DefaultCertValidator::verifyCertificate(X509* cert, const std::vector<std::strin
   }
 
   if (!subject_alt_name_matchers.empty()) {
-    if (!matchSubjectAltName(cert, subject_alt_name_matchers)) {
+    if (!matchSubjectAltName(cert, stream_info, subject_alt_name_matchers)) {
       const char* error = "verify cert failed: SAN matcher";
       if (error_details != nullptr) {
         *error_details = error;
@@ -299,7 +305,7 @@ DefaultCertValidator::verifyCertificate(X509* cert, const std::vector<std::strin
 ValidationResults DefaultCertValidator::doVerifyCertChain(
     STACK_OF(X509)& cert_chain, Ssl::ValidateResultCallbackPtr /*callback*/,
     const Network::TransportSocketOptionsConstSharedPtr& transport_socket_options, SSL_CTX& ssl_ctx,
-    const CertValidator::ExtraValidationContext& /*validation_context*/, bool is_server,
+    const CertValidator::ExtraValidationContext& context, bool is_server,
     absl::string_view host_name) {
   if (sk_X509_num(&cert_chain) == 0) {
     stats_.fail_verify_error_.inc();
@@ -352,7 +358,7 @@ ValidationResults DefaultCertValidator::doVerifyCertChain(
   std::string error_details;
   uint8_t tls_alert = SSL_AD_CERTIFICATE_UNKNOWN;
   const bool succeeded =
-      verifyCertAndUpdateStatus(leaf_cert, host_name, transport_socket_options.get(),
+      verifyCertAndUpdateStatus(leaf_cert, host_name, transport_socket_options.get(), context,
                                 detailed_status, &error_details, &tls_alert);
   return succeeded ? ValidationResults{ValidationResults::ValidationStatus::Successful,
                                        detailed_status, absl::nullopt, absl::nullopt}
@@ -380,15 +386,20 @@ bool DefaultCertValidator::verifySubjectAltName(X509* cert,
 }
 
 bool DefaultCertValidator::matchSubjectAltName(
-    X509* cert, const std::vector<SanMatcherPtr>& subject_alt_name_matchers) {
+    X509* cert, OptRef<const StreamInfo::StreamInfo> stream_info,
+    const std::vector<SanMatcherPtr>& subject_alt_name_matchers) {
   bssl::UniquePtr<GENERAL_NAMES> san_names(
       static_cast<GENERAL_NAMES*>(X509_get_ext_d2i(cert, NID_subject_alt_name, nullptr, nullptr)));
   if (san_names == nullptr) {
     return false;
   }
   for (const auto& config_san_matcher : subject_alt_name_matchers) {
     for (const GENERAL_NAME* general_name : san_names.get()) {
-      if (config_san_matcher->match(general_name)) {
+      if (stream_info) {
+        if (config_san_matcher->match(general_name, stream_info.ref())) {
+          return true;
+        }
+      } else if (config_san_matcher->match(general_name)) {
         return true;
       }
     }

source/common/tls/cert_validator/default_validator.h

@@ -62,7 +62,8 @@ class DefaultCertValidator : public CertValidator, Logger::Loggable<Logger::Id::
   Envoy::Ssl::ClientValidationStatus
   verifyCertificate(X509* cert, const std::vector<std::string>& verify_san_list,
                     const std::vector<SanMatcherPtr>& subject_alt_name_matchers,
-                    std::string* error_details, uint8_t* out_alert);
+                    OptRef<const StreamInfo::StreamInfo> stream_info, std::string* error_details,
+                    uint8_t* out_alert);
 
   /**
    * Verifies certificate hash for pinning. The hash is a hex-encoded SHA-256 of the DER-encoded
@@ -100,12 +101,13 @@ class DefaultCertValidator : public CertValidator, Logger::Loggable<Logger::Id::
    * @param subject_alt_name_matchers the configured matchers to match
    * @return true if the verification succeeds
    */
-  static bool matchSubjectAltName(X509* cert,
+  static bool matchSubjectAltName(X509* cert, OptRef<const StreamInfo::StreamInfo> stream_info,
                                   const std::vector<SanMatcherPtr>& subject_alt_name_matchers);
 
 private:
   bool verifyCertAndUpdateStatus(X509* leaf_cert, absl::string_view sni,
                                  const Network::TransportSocketOptions* transport_socket_options,
+                                 const CertValidator::ExtraValidationContext& validation_context,
                                  Envoy::Ssl::ClientValidationStatus& detailed_status,
                                  std::string* error_details, uint8_t* out_alert);
 

source/common/tls/cert_validator/san_matcher.cc

@@ -14,7 +14,7 @@ namespace Extensions {
 namespace TransportSockets {
 namespace Tls {
 
-bool StringSanMatcher::match(const GENERAL_NAME* general_name) const {
+bool StringSanMatcher::typeCompatible(const GENERAL_NAME* general_name) const {
   if (general_name->type != general_name_type_) {
     return false;
   }
@@ -23,9 +23,28 @@ bool StringSanMatcher::match(const GENERAL_NAME* general_name) const {
       return false;
     }
   }
+
+  return true;
+}
+
+bool StringSanMatcher::match(const GENERAL_NAME* general_name) const {
+  if (!typeCompatible(general_name)) {
+    return false;
+  }
+
   return matcher_.match(Utility::generalNameAsString(general_name));
 }
 
+bool StringSanMatcher::match(const GENERAL_NAME* general_name,
+                             const StreamInfo::StreamInfo& stream_info) const {
+  if (!typeCompatible(general_name)) {
+    return false;
+  }
+
+  Matchers::StringMatcher::Context context{makeOptRef(stream_info)};
+  return matcher_.match(Utility::generalNameAsString(general_name), context);
+}
+
 bool DnsExactStringSanMatcher::match(const GENERAL_NAME* general_name) const {
   if (general_name->type != GEN_DNS) {
     return false;

source/common/tls/cert_validator/san_matcher.h

@@ -24,6 +24,9 @@ namespace Ssl {
 class SanMatcher {
 public:
   virtual bool match(GENERAL_NAME const*) const PURE;
+  virtual bool match(GENERAL_NAME const* general_name, const StreamInfo::StreamInfo&) const {
+    return match(general_name);
+  }
   virtual ~SanMatcher() = default;
 };
 
@@ -40,6 +43,8 @@ using Ssl::SanMatcherPtr;
 class StringSanMatcher : public SanMatcher {
 public:
   bool match(const GENERAL_NAME* general_name) const override;
+  bool match(const GENERAL_NAME* general_name,
+             const StreamInfo::StreamInfo& stream_info) const override;
   ~StringSanMatcher() override = default;
 
   StringSanMatcher(int general_name_type, envoy::type::matcher::v3::StringMatcher matcher,
@@ -55,6 +60,8 @@ class StringSanMatcher : public SanMatcher {
   }
 
 private:
+  bool typeCompatible(const GENERAL_NAME* general_name) const;
+
   const int general_name_type_;
   const Envoy::Matchers::StringMatcherImpl matcher_;
   bssl::UniquePtr<ASN1_OBJECT> general_name_oid_;