This component provides a flexible DNS resolution system for ESP32 devices with support for multiple DNS protocols. It allows applications to resolve domain names using various transport methods, including standard UDP/TCP DNS, and securely resolve them using DNS over TLS (DoT) and DNS over HTTPS (DoH).

Features
Requirements
How to Use
Configuration
Certificate Options
Limitations
Performance Considerations
How It Works
Troubleshooting

Features

Multiple Protocol Support Choose from various DNS protocols:
- Standard UDP DNS (Port 53)
- TCP DNS (Port 53)
- DNS over TLS (DoT) (Port 853)
- DNS over HTTPS (DoH) (Port 443)
Secure DNS Resolution: Supports encrypted DNS queries using TLS and HTTPS to protect privacy and prevent DNS spoofing.
Flexible Configuration: Easily configure DNS servers, ports, timeouts, and protocol-specific options.
LWIP Integration: Seamlessly integrates with the ESP-IDF networking stack through LWIP hooks.
Standard getaddrinfo() Interface: Use the standard getaddrinfo() function to resolve domain names.

Requirements

ESP-IDF v5.0 or newer
Network connectivity (Wi-Fi or Ethernet)
For DoT/DoH: Sufficient RAM for TLS operations

How to Use

1. Enable custom DNS resolution

To enable custom DNS resolution, configure the CONFIG_LWIP_HOOK_NETCONN_EXT_RESOLVE_CUSTOM setting either through menuconfig or by adding CONFIG_LWIP_HOOK_NETCONN_EXT_RESOLVE_CUSTOM=y to your sdkconfig.defaults file to pre-set the configuration during the build process.

2. Configure DNS Settings

Initialize the DNS component with your preferred configuration:

#include "esp_dns.h"

/* Configure DNS over HTTPS */
esp_dns_config_t dns_config = {
    .dns_server = "dns.google",            /* DNS server hostname or IP address */
    .port = ESP_DNS_DEFAULT_DOH_PORT,      /* Optional: Server port (443 is default for HTTPS) */
    .timeout_ms = ESP_DNS_DEFAULT_TIMEOUT_MS, /* Optional: Request timeout in milliseconds (10000ms default) */
    .tls_config = {
        /* Optional: Use ESP-IDF certificate bundle for validating popular DNS providers */
        .crt_bundle_attach = esp_crt_bundle_attach,

        /* Or provide a custom certificate in PEM format (string) for your DNS server */
        /* Note: Only PEM format is supported; DER format certificates are not supported yet */
        .cert_pem = server_root_cert_pem_start,

        /* Note: If both crt_bundle_attach and cert_pem are provided,
           crt_bundle_attach is preferred over cert_pem */
    },
    .protocol_config.doh_config = {
        .url_path = "/dns-query",          /* Optional: DoH endpoint path on the server ("/dns-query" default) */
    }
};

/* Initialize DNS component based on protocol */
esp_dns_handle_t dns_handle = NULL;

/* Call esp_dns_init_doh() to use DNS over HTTPS */
dns_handle = esp_dns_init_doh(&dns_config);

/* or Call esp_dns_init_dot() to use DNS over TLS */
dns_handle = esp_dns_init_dot(&dns_config);

/* or Call esp_dns_init_tcp() to use DNS over TCP */
dns_handle = esp_dns_init_tcp(&dns_config);

/* or Call esp_dns_init_udp() to use DNS over UDP */
dns_handle = esp_dns_init_udp(&dns_config);

if (dns_handle == NULL) {
    ESP_LOGE(TAG, "Failed to initialize DNS");
    return;
}

3. Resolve Domain Names

Once initialized, the component automatically handles DNS resolution through the standard getaddrinfo() function:

struct addrinfo hints = {
    .ai_family = AF_UNSPEC,
    .ai_socktype = SOCK_STREAM,
};
struct addrinfo res;
int err = getaddrinfo("www.example.com", "80", &hints, &res);
if (err != 0) {
    ESP_LOGE(TAG, "DNS lookup failed: %d", err);
    return;
}
/* Use the resolved addresses */
/* ... */

/* Free the address info when done */
freeaddrinfo(res);

4. Cleanup

When you're done using the DNS component, clean up resources based on the protocol used:

int ret = 0;
/* Call esp_dns_cleanup_doh() to cleanup DNS over HTTPS */
ret = esp_dns_cleanup_doh(dns_handle);

/* or Call esp_dns_cleanup_dot() to cleanup DNS over TLS */
ret = esp_dns_cleanup_dot(dns_handle);

/* or Call esp_dns_cleanup_tcp() to cleanup DNS over TCP */
ret = esp_dns_cleanup_tcp(dns_handle);

/* or Call esp_dns_cleanup_udp() to cleanup DNS over UDP */
ret = esp_dns_cleanup_udp(dns_handle);

if (ret != 0) {
    ESP_LOGE(TAG, "Failed to cleanup DNS");
}

Configuration

Setting Up the ESP DNS Component

Navigate to your project directory.
Execute idf.py menuconfig.
Locate the Component config -> LWIP -> Hooks -> Netconn external resolve Hook section.
Change the setting to Custom implementation.

Common Settings

Parameter	Description	Default Value
`dns_server`	IP address or hostname of DNS server	`"8.8.8.8"` (Google DNS)
`port`	Server port number	Protocol-dependent (53, 853, or 443)
`timeout_ms`	Query timeout in milliseconds	`10000` (10 seconds)

TLS Configuration (for DoT and DoH)

Parameter	Description
`crt_bundle_attach`	Function pointer to attach certificate bundle
`server_cert`	SSL server certificate in PEM format
`alpn_protos`	ALPN protocols for DoH (typically `"h2"`)

Protocol-Specific Options

DoH Options

URL Path: URL path for DoH service (e.g., "/dns-query")

Certificate Options

When using secure DNS protocols (DoT and DoH), you have two certificate options:

Certificate Bundle: Use ESP-IDF's certificate bundle for validating connections to popular DNS providers.
Custom Certificate: Provide your own certificate in PEM format for custom DNS servers.

Limitations

The UDP DNS protocol implementation relies on the native LWIP DNS resolver.
Transport protocol selection must be configured through esp_dns_init_xxx() rather than getaddrinfo() parameters due to LWIP resolver hook limitations.
Maximum response size is limited by the buffer size (default: 512 bytes) for DNS over TLS (DOT) and TCP protocols.
Only one DNS protocol can be active at a time.
Resolution Speed:
- UDP DNS is fastest but least secure
- DoH typically has the highest latency but offers the best security

Performance Considerations

Memory Usage: DoH and DoT require more memory due to TLS overhead:

TBD: Fill in the memory usage for each protocol

How It Works

This component utilizes the CONFIG_LWIP_HOOK_NETCONN_EXT_RESOLVE_CUSTOM hook to override the core DNS functionality of LWIP and implement custom DNS over HTTPS resolution. To enable this, ensure that the configuration option Component config → LWIP → Hooks → Netconn external resolve Hook is set to Custom implementation.

Once you add this component to your project, it will replace the default LWIP DNS resolution automatically.

⚠️ Warning: This component cannot work alongside other components that use the CONFIG_LWIP_HOOK_NETCONN_EXT_RESOLVE_CUSTOM hook.

Troubleshooting

Connection Issues:
- Ensure network connectivity and correct DNS server configuration
- Verify that your network allows the required ports (53, 853, or 443)
Certificate Errors:
- Verify that the correct certificate is provided for secure protocols
- For public DNS servers, use the certificate bundle approach
Timeout Errors:
- Increase the timeout value for slow network connections
- Try a different DNS server that might be geographically closer
Memory Issues:
- If you encounter memory errors, consider increasing the task stack size
- For memory-constrained devices, prefer UDP DNS.

README.md

ESP DNS Component

Table of Contents