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).
- **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:
```C
#include"esp_dns.h"
/* Configure DNS over HTTPS */
esp_dns_config_tdns_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_tdns_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:
| `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:
1.**Certificate Bundle**: Use ESP-IDF's certificate bundle for validating connections to popular DNS providers.
2.**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.