dns: add a new RUST-based DNS resolver extension

CODEOWNERS

@@ -283,6 +283,7 @@ extensions/upstreams/tcp @ggreenway @mattklein123
 /*/extensions/network/dns_resolver/cares @yanavlasov @mattklein123
 /*/extensions/network/dns_resolver/apple @yanavlasov @mattklein123
 /*/extensions/network/dns_resolver/getaddrinfo @fredyw @mattklein123
+/*/extensions/network/dns_resolver/hickory @agrawroh @yanavlasov @wbpcode
 # compression code
 /*/extensions/filters/http/decompressor @kbaichoo @mattklein123
 /*/extensions/filters/http/compressor @kbaichoo @mattklein123

api/BUILD

@@ -366,6 +366,7 @@ proto_library(
         "//envoy/extensions/network/dns_resolver/apple/v3:pkg",
         "//envoy/extensions/network/dns_resolver/cares/v3:pkg",
         "//envoy/extensions/network/dns_resolver/getaddrinfo/v3:pkg",
+        "//envoy/extensions/network/dns_resolver/hickory/v3:pkg",
         "//envoy/extensions/network/socket_interface/v3:pkg",
         "//envoy/extensions/outlier_detection_monitors/common/v3:pkg",
         "//envoy/extensions/outlier_detection_monitors/consecutive_errors/v3:pkg",

api/envoy/extensions/network/dns_resolver/hickory/v3/BUILD

@@ -0,0 +1,12 @@
+# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = [
+        "//envoy/config/core/v3:pkg",
+        "@xds//udpa/annotations:pkg",
+    ],
+)

api/envoy/extensions/network/dns_resolver/hickory/v3/hickory_dns_resolver.proto

@@ -0,0 +1,93 @@
+syntax = "proto3";
+
+package envoy.extensions.network.dns_resolver.hickory.v3;
+
+import "envoy/config/core/v3/address.proto";
+
+import "google/protobuf/duration.proto";
+import "google/protobuf/wrappers.proto";
+
+import "udpa/annotations/status.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.network.dns_resolver.hickory.v3";
+option java_outer_classname = "HickoryDnsResolverProto";
+option java_multiple_files = true;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/network/dns_resolver/hickory/v3;hickoryv3";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: Hickory DNS resolver]
+// [#extension: envoy.network.dns_resolver.hickory]
+
+// Configuration for DNS-over-TLS (DoT) servers.
+message DnsOverTlsConfig {
+  // DNS-over-TLS server addresses. The port should typically be 853.
+  repeated config.core.v3.Address servers = 1;
+
+  // The SNI hostname to use for TLS verification. Required when servers are specified.
+  string tls_server_name = 2 [(validate.rules).string = {min_len: 1}];
+}
+
+// Configuration for DNS-over-HTTPS (DoH) servers.
+message DnsOverHttpsConfig {
+  // DNS-over-HTTPS endpoint URLs (e.g., ``https://dns.google/dns-query``).
+  repeated string server_urls = 1 [(validate.rules).repeated = {items {string {min_len: 1}}}];
+}
+
+// Configuration for the Hickory DNS resolver. This resolver uses the Hickory DNS library,
+// a pure Rust DNS implementation, for DNS resolution. It supports standard DNS (UDP/TCP),
+// DNS-over-TLS (DoT), DNS-over-HTTPS (DoH), and ``DNSSEC`` validation.
+//
+// The resolver runs asynchronously on its own ``Tokio`` runtime threads, separate from Envoy's
+// event loop threads. Results are delivered back to the calling dispatcher thread.
+// [#next-free-field: 10]
+message HickoryDnsResolverConfig {
+  // A list of DNS resolver addresses for standard UDP/TCP resolution.
+  // If not specified and ``use_system_config`` is true (the default), the system configuration
+  // (``/etc/resolv.conf`` on Unix) will be used.
+  repeated config.core.v3.Address resolvers = 1;
+
+  // Configuration for DNS-over-TLS (DoT). When specified, queries will be sent over TLS
+  // to the configured servers.
+  DnsOverTlsConfig dns_over_tls = 2;
+
+  // Configuration for DNS-over-HTTPS (DoH). When specified, queries will be sent over
+  // HTTPS to the configured endpoints.
+  DnsOverHttpsConfig dns_over_https = 3;
+
+  // Enable ``DNSSEC`` validation for DNS responses. When enabled, the resolver will validate
+  // ``DNSSEC`` signatures and reject responses that fail validation.
+  //
+  // Defaults to false.
+  bool enable_dnssec = 4;
+
+  // Maximum number of entries in the DNS response cache. The cache uses an LRU eviction
+  // policy and supports negative caching (caching of NXDOMAIN/NODATA responses).
+  //
+  // Defaults to 1024.
+  google.protobuf.UInt32Value cache_size = 5;
+
+  // Number of threads in the ``Tokio`` runtime used for asynchronous DNS resolution.
+  // Each resolver instance runs its own ``Tokio`` runtime.
+  //
+  // Defaults to 2. Maximum is 16.
+  google.protobuf.UInt32Value num_resolver_threads = 6 [(validate.rules).uint32 = {lte: 16 gte: 1}];
+
+  // If true, read the system DNS configuration (``/etc/resolv.conf`` on Unix) for name server
+  // addresses and search domains. When ``resolvers`` are also specified, they take precedence
+  // over the system configuration.
+  //
+  // Defaults to true when no ``resolvers``, ``dns_over_tls``, or ``dns_over_https`` are specified.
+  bool use_system_config = 7;
+
+  // Timeout for each individual DNS query attempt.
+  //
+  // Defaults to 5 seconds.
+  google.protobuf.Duration query_timeout = 8 [(validate.rules).duration = {gte {nanos: 1000000}}];
+
+  // Maximum number of query attempts before the resolver gives up. Each attempt may use
+  // a different name server.
+  //
+  // Defaults to 3.
+  google.protobuf.UInt32Value query_tries = 9 [(validate.rules).uint32 = {gte: 1}];
+}

api/versioning/BUILD

@@ -306,6 +306,7 @@ proto_library(
         "//envoy/extensions/network/dns_resolver/apple/v3:pkg",
         "//envoy/extensions/network/dns_resolver/cares/v3:pkg",
         "//envoy/extensions/network/dns_resolver/getaddrinfo/v3:pkg",
+        "//envoy/extensions/network/dns_resolver/hickory/v3:pkg",
         "//envoy/extensions/network/socket_interface/v3:pkg",
         "//envoy/extensions/outlier_detection_monitors/common/v3:pkg",
         "//envoy/extensions/outlier_detection_monitors/consecutive_errors/v3:pkg",

bazel/dependency_imports.bzl

@@ -259,3 +259,8 @@ def crates_repositories():
         # lockfile = Label("@envoy//source/extensions/dynamic_modules/sdk/rust:Cargo.Bazel.lock"),
         manifests = ["@envoy//source/extensions/dynamic_modules/sdk/rust:Cargo.toml"],
     )
+    crates_repository(
+        name = "hickory_dns_crate_index",
+        cargo_lockfile = "@envoy//source/extensions/network/dns_resolver/hickory/rust:Cargo.lock",
+        manifests = ["@envoy//source/extensions/network/dns_resolver/hickory/rust:Cargo.toml"],
+    )

bazel/dependency_imports_extra.bzl

@@ -1,7 +1,9 @@
 load("@dynamic_modules_rust_sdk_crate_index//:defs.bzl", "crate_repositories")
+load("@hickory_dns_crate_index//:defs.bzl", hickory_dns_crate_repositories = "crate_repositories")
 load("@llvm_toolchain//:toolchains.bzl", "llvm_register_toolchains")
 
 # Dependencies that rely on a first stage of envoy_dependency_imports() in dependency_imports.bzl.
 def envoy_dependency_imports_extra():
     crate_repositories()
+    hickory_dns_crate_repositories()
     llvm_register_toolchains()

bazel/deps.yaml

@@ -1290,6 +1290,7 @@ rules_rust:
   - dataplane_core
   - dataplane_ext
   extensions:
+  - envoy.network.dns_resolver.hickory
   - envoy.wasm.runtime.wasmtime
   license: "Apache-2.0"
   license_url: "https://github.com/bazelbuild/rules_rust/blob/{version}/LICENSE.txt"
@@ -1348,6 +1349,7 @@ toolchains_llvm:
   use_category:
   - build
   - dataplane_core
+  - dataplane_ext
   - controlplane
   implied_untracked_deps:
   - llvm_toolchain_llvm

changelogs/current.yaml

@@ -278,6 +278,11 @@ removed_config_or_runtime:
 # *Normally occurs at the end of the* :ref:`deprecation period <deprecated>`
 
 new_features:
+- area: dns_resolver
+  change: |
+    Added :ref:`HickoryDnsResolverConfig
+    <envoy_v3_api_msg_extensions.network.dns_resolver.hickory.v3.HickoryDnsResolverConfig>`, a new DNS
+    resolver using the `Hickory DNS <https://github.com/hickory-dns/hickory-dns>`_ library.
 - area: dynamic_modules
   change: |
     Added upstream HTTP TCP bridge extension for dynamic modules. This enables modules to transform

docs/root/intro/arch_overview/upstream/dns_resolution.rst

@@ -13,14 +13,18 @@ Envoy uses `c-ares <https://github.com/c-ares/c-ares>`_ as a third party DNS res
 On Apple OSes Envoy additionally offers resolution using Apple specific APIs via the
 ``envoy.restart_features.use_apple_api_for_dns_lookups`` runtime feature.
 
-Envoy provides DNS resolution through extensions, and contains 3 built-in extensions:
+Envoy provides DNS resolution through extensions, and contains 4 built-in extensions:
 
 1) c-ares: :ref:`CaresDnsResolverConfig<envoy_v3_api_msg_extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig>`
 
 2) Apple (iOS/macOS only): :ref:`AppleDnsResolverConfig<envoy_v3_api_msg_extensions.network.dns_resolver.apple.v3.AppleDnsResolverConfig>`
 
 3) getaddrinfo: :ref:`GetAddrInfoDnsResolverConfig <envoy_v3_api_msg_extensions.network.dns_resolver.getaddrinfo.v3.GetAddrInfoDnsResolverConfig>`
 
+4) Hickory DNS: :ref:`HickoryDnsResolverConfig <envoy_v3_api_msg_extensions.network.dns_resolver.hickory.v3.HickoryDnsResolverConfig>`
+   A pure Rust DNS resolver supporting standard DNS (UDP/TCP), DNS-over-TLS (DoT), DNS-over-HTTPS (DoH),
+   and DNSSEC validation. It runs on its own Tokio runtime threads via the dynamic modules framework.
+
 For an example of a built-in DNS typed configuration see the :ref:`HTTP filter configuration documentation <config_http_filters_dynamic_forward_proxy>`.
 
 The c-ares based DNS Resolver emits the following stats rooted in the ``dns.cares`` stats tree:

source/common/protobuf/BUILD

@@ -161,6 +161,7 @@ envoy_cc_library(
         "@envoy_api//envoy/extensions/network/dns_resolver/apple/v3:pkg_cc_proto_descriptor",
         "@envoy_api//envoy/extensions/network/dns_resolver/cares/v3:pkg_cc_proto_descriptor",
         "@envoy_api//envoy/extensions/network/dns_resolver/getaddrinfo/v3:pkg_cc_proto_descriptor",
+        "@envoy_api//envoy/extensions/network/dns_resolver/hickory/v3:pkg_cc_proto_descriptor",
         "@envoy_api//envoy/extensions/network/socket_interface/v3:pkg_cc_proto_descriptor",
         "@envoy_api//envoy/extensions/path/match/uri_template/v3:pkg_cc_proto_descriptor",
         "@envoy_api//envoy/extensions/path/rewrite/uri_template/v3:pkg_cc_proto_descriptor",

source/common/protobuf/create_reflectable_message.cc

@@ -112,6 +112,7 @@ Protobuf::ReflectableMessage createReflectableMessage(const Protobuf::Message& m
 #include "envoy/extensions/network/dns_resolver/apple/v3/apple_dns_resolver_descriptor.pb.h"
 #include "envoy/extensions/network/dns_resolver/cares/v3/cares_dns_resolver_descriptor.pb.h"
 #include "envoy/extensions/network/dns_resolver/getaddrinfo/v3/getaddrinfo_dns_resolver_descriptor.pb.h"
+#include "envoy/extensions/network/dns_resolver/hickory/v3/hickory_dns_resolver_descriptor.pb.h"
 #include "envoy/extensions/network/socket_interface/v3/default_socket_interface_descriptor.pb.h"
 #include "envoy/extensions/path/match/uri_template/v3/uri_template_match_descriptor.pb.h"
 #include "envoy/extensions/path/rewrite/uri_template/v3/uri_template_rewrite_descriptor.pb.h"
@@ -338,6 +339,8 @@ std::unique_ptr<TextFormatTranscoder> createTranscoder() {
       protobuf::reflection::
           envoy_extensions_network_dns_resolver_getaddrinfo_v3_getaddrinfo_dns_resolver::
               kFileDescriptorInfo,
+      protobuf::reflection::envoy_extensions_network_dns_resolver_hickory_v3_hickory_dns_resolver::
+          kFileDescriptorInfo,
       protobuf::reflection::envoy_extensions_network_socket_interface_v3_default_socket_interface::
           kFileDescriptorInfo,
       protobuf::reflection::envoy_extensions_path_match_uri_template_v3_uri_template_match::

source/extensions/extensions_build_config.bzl

@@ -537,6 +537,8 @@ EXTENSIONS = {
     "envoy.network.dns_resolver.apple":                "//source/extensions/network/dns_resolver/apple:config",
     # getaddrinfo DNS resolver extension can be used when the system resolver is desired (e.g., Android)
     "envoy.network.dns_resolver.getaddrinfo":          "//source/extensions/network/dns_resolver/getaddrinfo:config",
+    # Hickory DNS resolver extension uses a Rust-based DNS library with support for DoT, DoH, and `DNSSEC`.
+    "envoy.network.dns_resolver.hickory":              "//source/extensions/network/dns_resolver/hickory:config",
 
     #
     # Address Resolvers

source/extensions/extensions_metadata.yaml

@@ -1764,6 +1764,13 @@ envoy.network.dns_resolver.getaddrinfo:
   status: stable
   type_urls:
   - envoy.extensions.network.dns_resolver.getaddrinfo.v3.GetAddrInfoDnsResolverConfig
+envoy.network.dns_resolver.hickory:
+  categories:
+  - envoy.network.dns_resolver
+  security_posture: robust_to_untrusted_downstream_and_upstream
+  status: alpha
+  type_urls:
+  - envoy.extensions.network.dns_resolver.hickory.v3.HickoryDnsResolverConfig
 envoy.resolvers.reverse_connection:
   categories:
   - envoy.resolvers

source/extensions/network/dns_resolver/hickory/BUILD

@@ -0,0 +1,33 @@
+load(
+    "//bazel:envoy_build_system.bzl",
+    "envoy_cc_extension",
+    "envoy_cc_library",
+    "envoy_extension_package",
+)
+
+licenses(["notice"])  # Apache 2
+
+envoy_extension_package()
+
+envoy_cc_library(
+    name = "hickory_dns_lib",
+    srcs = ["hickory_dns_impl.cc"],
+    hdrs = ["hickory_dns_impl.h"],
+    deps = [
+        "//envoy/event:dispatcher_interface",
+        "//envoy/network:dns_interface",
+        "//envoy/network:dns_resolver_interface",
+        "//envoy/registry",
+        "//source/common/network:utility_lib",
+        "//source/extensions/dynamic_modules:dynamic_modules_lib",
+        "@envoy_api//envoy/extensions/network/dns_resolver/hickory/v3:pkg_cc_proto",
+    ],
+)
+
+envoy_cc_extension(
+    name = "config",
+    deps = [
+        ":hickory_dns_lib",
+        "//source/extensions/network/dns_resolver/hickory/rust:hickory_dns_static",
+    ],
+)