dotdoh: add DNS-over-QUIC (RFC 9250) up- and downstream

DoQ is the last IETF standards-track encrypted DNS transport we did not speak,
and the cheapest one to add: the DNS message rides a QUIC stream with the same
2-byte length prefix DoT already uses, so on top of the OpenSSL QUIC stack the
DoH3 work brought in there is no HTTP layer at all. Both directions land
together because they share that stack.

1. Outbound: `doq://host` becomes a `dns.upstreams` scheme (the `quic://`
   spelling AdGuard and dnsproxy configs use is accepted as an alias),
   defaulting to UDP port 853. The exchange is fail-closed exactly like
   DoT/DoH/DoH3 - a bad chain, a reset stream or a timeout drops the query so
   dnsmasq fails over rather than downgrading to plaintext. Per RFC 9250
   Sec. 4.2.1 the Message ID goes out as 0 and dnsmasq's own ID is restored on
   the answer.
2. Inbound: `dns.doq` (default on, like `dns.dot`) brings up a listener on
   UDP/853 - the same port number DoT uses on TCP, which does not collide. It is
   a single-threaded event loop in the shape of the DoT listener: OpenSSL owns
   the QUIC transport while every in-flight query is a small non-blocking state
   machine, so a slow resolve never stalls another connection and a flood costs
   a bounded state record rather than a thread. Queries are attributed to the
   real downstream client through the same private-EDNS handoff as DoT/DoH, and
   answers are padded per RFC 8467 when the client asked for it.
3. The socket, handshake and timer plumbing the DoH3 client already carried
   moves into `quic_common.c`, so both QUIC clients share one context, one trust
   store and one fail-closed verify instead of duplicating them. DoQ is gated on
   the new `HAVE_QUIC` (OpenSSL >= 4.0) rather than `HAVE_HTTP3`, so a build
   without nghttp3 still speaks it.

Worth calling out on the hardening side: QUIC address validation (Retry) stays
on so we cannot be used to amplify towards a forged source, 0-RTT is explicitly
disabled because a replayed early-data query would be answered and logged twice,
only the `doq` ALPN is accepted, and connections, per-source connections,
concurrent streams and per-connection queries are each capped. RFC 9250
Sec. 5.5.2 makes `edns-tcp-keepalive` a protocol error on DoQ, so a query
carrying it closes the connection.

One wrinkle needed solving: OpenSSL's QUIC API exposes the peer address but no
per-connection *local* address, and the listener is wildcard-bound, so - unlike
DoT and DoH - we cannot simply read off which of our addresses the client
reached. Conveying nothing is not an option: the answer would then be built from
the interface of our own loopback handoff, so `pi.hole` would resolve to
127.0.0.1 for every DoQ client, and a CNAME chain reaching it would write that
into the shared cache record. We therefore ask the kernel which source address it
would use to reach that peer - the address it would itself put on a reply
datagram, and so the one a plain-DNS answer is built from - and convey that.

Signed-off-by: DL6ER <dl6er@dl6er.de>

Author: DL6ER

.gitignore

@@ -4,6 +4,7 @@ pihole-FTL*
 # Generated standalone regression test binaries (built via ./build.sh test)
 /tar_regression
 /gzip_regression
+/dotdoh_regression
 
 # Generated pihole.toml file
 pihole.toml

src/CMakeLists.txt

@@ -594,6 +594,17 @@ if(LIBSSL AND LIBCRYPTO AND USE_TLS)
 #endif
 int main(void) { return 0; }
 " OPENSSL_HAS_QUIC_PEER_ADDR)
+
+    # DoQ (RFC 9250) rides on OpenSSL's QUIC alone - it carries DNS directly on
+    # QUIC streams, so unlike DoH3 it needs no HTTP/3 library. Gate it on the
+    # OpenSSL version only, so a build without nghttp3 still speaks DoQ.
+    if(OPENSSL_HAS_QUIC_PEER_ADDR)
+        message(STATUS "Building FTL with DoQ (DNS-over-QUIC) support: YES")
+        target_compile_definitions(dotdoh PRIVATE HAVE_QUIC)
+    else()
+        message(STATUS "Building FTL with DoQ (DNS-over-QUIC) support: NO (OpenSSL < 4.0)")
+    endif()
+
     find_library(LIBNGHTTP3 NAMES libnghttp3${LIBRARY_SUFFIX} nghttp3)
     if(LIBNGHTTP3 AND OPENSSL_HAS_QUIC_PEER_ADDR)
         message(STATUS "Building FTL with HTTP/3 support: YES")

src/api/docs/content/specs/config.yaml

@@ -301,6 +301,8 @@ components:
                   type: boolean
                 dot:
                   type: boolean
+                doq:
+                  type: boolean
                 blocking:
                   type: object
                   properties:
@@ -775,6 +777,7 @@ components:
             upstreamCA: ""
             doh: true
             dot: true
+            doq: true
             CNAMEdeepInspect: true
             blockESNI: true
             EDNS0ECS: true

src/config/config.c

@@ -604,7 +604,7 @@ void initConfig(struct config *conf)
 	conf->dns.revServers.f = FLAG_RESTART_FTL;
 
 	conf->dns.upstreamCA.k = "dns.upstreamCA";
-	conf->dns.upstreamCA.h = "Path to a CA certificate bundle used to verify encrypted upstream servers (DoT/DoH). If left empty, the system default trust store is used. Only relevant when at least one dns.upstreams entry uses the tls:// or https:// scheme.";
+	conf->dns.upstreamCA.h = "Path to a CA certificate bundle used to verify encrypted upstream servers (DoT/DoH). If left empty, the system default trust store is used. Only relevant when at least one dns.upstreams entry uses an encrypted scheme (tls://, https://, h3:// or doq://).";
 	conf->dns.upstreamCA.a = cJSON_CreateStringReference("A path to a PEM CA bundle, or empty for the system default trust store");
 	conf->dns.upstreamCA.t = CONF_STRING;
 	conf->dns.upstreamCA.d.s = (char*)"";
@@ -625,6 +625,13 @@ void initConfig(struct config *conf)
 	conf->dns.dot.f = FLAG_RESTART_FTL;
 	conf->dns.dot.c = validate_stub;
 
+	conf->dns.doq.k = "dns.doq";
+	conf->dns.doq.h = "Enable the inbound DNS-over-QUIC (DoQ) server on UDP port 853. When enabled, FTL terminates DoQ connections directly (RFC 9250) so downstream clients can use this Pi-hole as their encrypted resolver. DoQ carries DNS on QUIC streams and shares port number 853 with DoT without colliding (UDP vs. TCP). Requires a valid TLS certificate (the same one configured for the webserver) and an FTL built with QUIC support.";
+	conf->dns.doq.t = CONF_BOOL;
+	conf->dns.doq.d.b = true;
+	conf->dns.doq.f = FLAG_RESTART_FTL;
+	conf->dns.doq.c = validate_stub;
+
 	// sub-struct dns.cache
 	conf->dns.domain.name.k = "dns.domain.name";
 	conf->dns.domain.name.h = "The DNS domain used by your Pi-hole.\n\n This DNS domain is purely local. FTL may answer queries from its local cache and configuration but *never* forwards any requests upstream *unless* you have configured a dns.revServer exactly for this domain. In the latter case, all queries for this domain are sent exclusively to this server (including reverse lookups).\n\n For DHCP, this has two effects; firstly it causes the DHCP server to return the domain to any hosts which request it, and secondly it sets the domain which it is legal for DHCP-configured hosts to claim. The intention is to constrain hostnames so that an untrusted host on the LAN cannot advertise its name via DHCP as e.g. \"google.com\" and capture traffic not meant for it. If no domain suffix is specified, then any DHCP hostname with a domain part (ie with a period) will be disallowed and logged. If a domain is specified, then hostnames with a domain part are allowed, provided the domain part matches the suffix. In addition, when a suffix is set then hostnames without a domain part have the suffix added as an optional domain part. For instance, we can set domain=mylab.com and have a machine whose DHCP hostname is \"laptop\". The IP address for that machine is available both as \"laptop\" and \"laptop.mylab.com\".\n\n You can disable setting a domain by setting this option to an empty string.";

src/config/config.h

@@ -158,6 +158,7 @@ struct config {
 		struct conf_item upstreamCA;
 		struct conf_item doh;
 		struct conf_item dot;
+		struct conf_item doq;
 		struct {
 			struct conf_item name;
 			struct conf_item local;

src/config/validator.c

@@ -810,8 +810,8 @@ bool validate_str_no_newline(union conf_value *val, const char *key, char err[VA
 
 // Validator for dns.upstreams. Enforces the same array/string/newline rules as
 // validate_array_no_newline() and, in addition, requires every encrypted entry
-// (tls:// or https://) to parse as a valid encrypted-upstream URI. Plaintext
-// entries are left untouched - dnsmasq validates those itself.
+// (tls://, https://, h3:// or doq://) to parse as a valid encrypted-upstream
+// URI. Plaintext entries are left untouched - dnsmasq validates those itself.
 bool validate_upstreams(union conf_value *val, const char *key, char err[VALIDATOR_ERRBUF_LEN])
 {
 	if(!validate_array_no_newline(val, key, err))
@@ -825,11 +825,11 @@ bool validate_upstreams(union conf_value *val, const char *key, char err[VALIDAT
 			continue;
 
 		// Anything carrying a URI scheme ("://") must be a supported encrypted
-		// upstream (tls:// or https://) that parses cleanly. A plaintext server
-		// specification handled downstream by dnsmasq never contains "://", so
-		// an entry that does but is not a valid encrypted URI (e.g. http://,
-		// ftp:// or a malformed tls://) is rejected here rather than being
-		// written into dnsmasq.conf and breaking DNS startup.
+		// upstream (tls://, https://, h3:// or doq://) that parses cleanly. A
+		// plaintext server specification handled downstream by dnsmasq never
+		// contains "://", so an entry that does but is not a valid encrypted URI
+		// (e.g. http://, ftp:// or a malformed tls://) is rejected here rather
+		// than being written into dnsmasq.conf and breaking DNS startup.
 		if(strstr(s, "://") != NULL)
 		{
 			struct upstream_uri u;

src/dnsmasq_interface.c

@@ -3746,6 +3746,14 @@ void FTL_fork_and_bind_sockets(struct passwd *ent_pw, bool dnsmasq_start)
 			log_crit("Unable to create dotdoh DoT thread. Exiting...");
 			exit(EXIT_FAILURE);
 		}
+
+		// Likewise for the inbound DoQ (DNS-over-QUIC) listener on UDP/853.
+		if(config.dns.doq.v.b &&
+		   pthread_create( &threads[DOTDOH_DOQ], &attr, dotdoh_doq_thread, NULL ) != 0)
+		{
+			log_crit("Unable to create dotdoh DoQ thread. Exiting...");
+			exit(EXIT_FAILURE);
+		}
 	}
 
 	// Chown files if FTL started as user root but a dnsmasq config

src/dotdoh/CMakeLists.txt

@@ -19,15 +19,20 @@ set(dotdoh_sources
         registry.h
         tls_client.c
         tls_client.h
+        quic_common.c
+        quic_common.h
         quic_client.c
         quic_client.h
+        doq_client.c
+        doq_client.h
         proxy.c
         proxy.h
         server.c
         server.h
         source_filter.c
         source_filter.h
         dot_server.c
+        doq_server.c
         )
 
 add_library(dotdoh OBJECT ${dotdoh_sources})