DNS-over-HTTPS (DoH) Complete Guide: Resolution Flow, Server Setup, and Python Client

# /etc/nginx/sites-available/doh
server {
    listen 443 ssl http2;
    server_name dns.example.com;

    # TLS 1.3 only for minimum latency
    ssl_protocols TLSv1.3;
    ssl_ciphers TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256;
    ssl_certificate /etc/ssl/certs/dns.example.com.crt;
    ssl_certificate_key /etc/ssl/private/dns.example.com.key;

    location = /dns-query {
        # Only POST method per RFC 8484
        limit_except POST { deny all; }

        # Proxy to local DNS resolver (Unbound, CoreDNS)
        proxy_pass http://127.0.0.1:53;
        proxy_set_header X-Forwarded-For $remote_addr;

        # DoH requires specific content type
        proxy_set_header Content-Type application/dns-message;

        # Large enough for DNS responses (max ~4K)
        proxy_buffer_size 4k;
        proxy_buffers 8 4k;
    }

    # Health check endpoint
    location = /health { return 200 "OK"; }
}

import dns.message
import dns.rdatatype
import httpx

class DoHClient:
    """DNS-over-HTTPS client using RFC 8484 wire format.

    Encodes DNS queries as binary DNS wire format, sends them
    via HTTPS POST with content-type application/dns-message,
    and decodes the response.
    """

    PROVIDERS = {
        "cloudflare": "https://1.1.1.1/dns-query",
        "google": "https://dns.google/dns-query",
        "quad9": "https://dns.quad9.net/dns-query",
    }

    def __init__(self, provider: str = "cloudflare"):
        self.url = self.PROVIDERS.get(provider, provider)
        self.client = httpx.Client(http2=True)  # HTTP/2 for efficiency

    def resolve(self, domain: str, record_type: str = "A") -> list:
        """Resolve a DNS record via DoH.

        Args:
            domain: Domain to query (e.g., 'example.com')
            record_type: DNS record type ('A', 'AAAA', 'MX', etc.)

        Returns:
            List of answer strings (e.g., ['93.184.216.34'])

        Raises:
            httpx.HTTPError: If the DoH server is unreachable
            dns.exception.DNSException: If the DNS response is malformed
        """
        # Build DNS query in wire format
        query = dns.message.make_query(domain, dns.rdatatype.from_text(record_type))
        wire_query = query.to_wire()

        # Send via HTTPS POST (RFC 8484 Section 4.1.1)
        response = self.client.post(
            self.url,
            content=wire_query,
            headers={"Content-Type": "application/dns-message"},
            timeout=10.0
        )
        response.raise_for_status()

        # Parse DNS response from wire format
        answer = dns.message.from_wire(response.content)
        results = []
        for rrset in answer.answer:
            for rdata in rrset:
                results.append(str(rdata))

        return results

# Usage
client = DoHClient("cloudflare")

# A record lookup
ips = client.resolve("example.com", "A")
print(f"example.com A records: {ips}")  # ['93.184.216.34']

# MX record lookup
mx = client.resolve("gmail.com", "MX")
print(f"gmail.com MX records: {mx}")    # ['5 gmail-smtp-in.l.google.com.', ...]

# /etc/systemd/resolved.conf
[Resolve]
DNS=1.1.1.1 1.0.0.1
DNSOverHTTPS=yes
DNSSEC=yes

sudo systemctl restart systemd-resolved

# Verify
resolvectl status

about:config → network.trr.mode = 3 (Force DoH)
about:config → network.trr.uri = https://1.1.1.1/dns-query