feat(common): Add ESP DNS module with support for UDP, DoT, and DoH protocols #781

espressif-abhikroy · 2025-03-14T11:07:42Z

This commit introduces a custom DNS module for ESP32, enabling DNS resolution capabilities over various protocols including traditional UDP, TCP, DNS over TLS (DoT), and DNS over HTTPS (DoH). The module includes initialization, cleanup, and error handling functionalities, along with protocol-specific implementations for each DNS type.

Description

Testing

Checklist

Before submitting a Pull Request, please ensure the following:

🚨 This PR does not introduce breaking changes.
All CI checks (GH Actions) pass.
Documentation is updated as needed.
Tests are updated or added as necessary.
Code is well-commented, especially in complex areas.
Git history is clean — commits are squashed to the minimum necessary.

…rotocols This commit introduces a custom DNS module for ESP32, enabling DNS resolution capabilities over various protocols including traditional UDP, DNS over TLS (DoT), and DNS over HTTPS (DoH). The module includes initialization, cleanup, and error handling functionalities, along with protocol-specific implementations for each DNS type.

david-cermak · 2025-03-25T11:48:00Z

components/esp_dns/README.md

+| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-P4 | ESP32-S2 | ESP32-S3 |
+| ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | -------- | -------- | -------- |


we usually place this in example README's -- I'd suggest removing from component's docs as this DNS module should support all targets

david-cermak · 2025-03-25T11:49:59Z

components/esp_dns/README.md

+
+- **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.


what about coexistence with Thread lib (or any other user of that hook)?

david-cermak · 2025-03-25T11:50:35Z

components/esp_dns/README.md

+
+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, such as the OpenThread component.


Oh, I see 👍

david-cermak · 2025-03-25T11:51:42Z

components/esp_dns/README.md

+
+### 1. Add Component to Your Project
+
+Add the ESP DNS component to your project's `components` directory or include it as a dependency in your project's `idf_component.yml` file.


the most common way: idf.py add-dependency

Also, this README also appear in the component manager so this information is already presented to user. This section is useful only if the user is reading it out of the component manager page.

david-cermak · 2025-03-25T11:53:13Z

components/esp_dns/README.md

+    .port = 443, // Optional, default is 443
+    .timeout_ms = 5000, // Optional, default is 5000
+    .tls_config = {
+        .crt_bundle_attach = esp_crt_bundle_attach, // Optional, default is NULL


esp_crt_bundle_attach is not optional, right, if it defaults to NULL?

david-cermak · 2025-03-25T11:56:19Z

components/esp_dns/esp_dns.c

+
+
+/* Global DNS handle instance */
+static esp_dns_handle_t g_dns_handle = NULL;


Suggested change

static esp_dns_handle_t g_dns_handle = NULL;

static esp_dns_handle_t s_dns_handle = NULL;

since declared as static

david-cermak · 2025-03-25T11:58:03Z

components/esp_dns/esp_dns.c

+    static struct dns_handle instance;
+    static bool initialized = false;


Question: Could we remove the static modifiers so the component could be used with multiple handles? e.g. one DoH another DoT?

david-cermak · 2025-03-25T12:00:05Z

components/esp_dns/esp_dns.c

+
+/* ========================= LWIP HOOK FUNCTIONS ========================= */
+
+#if defined(CONFIG_LWIP_HOOK_NETCONN_EXT_RESOLVE_CUSTOM)


can we move it to some lwip specific module?

Move the hook to lwip specific file.

david-cermak

Very useful component, generally LGTM, just left a few nitpicks. Nice work!

david-cermak · 2025-03-25T12:35:14Z

components/esp_dns/include/esp_dns.h

+#define DEFAULT_TCP_PORT 53 /* Default TCP port */
+#define DEFAULT_DOT_PORT 853 /* Default TLS port */
+#define DEFAULT_DOH_PORT 443 /* Default HTTPS port */
+
+#define DEFAULT_TIMEOUT_MS 5000


suggest namespacing with ESP_ or ESP_DNS (since this is a public header and DEFAULT_TCP_PORT is a just a common name)

david-cermak · 2025-03-25T12:37:49Z

components/esp_dns/examples/esp_dns_basic/main/esp_dns_example.c

+#endif /* ENABLE_TCP */
+
+#if ENABLE_DOT_CERT
+    /*---------- DNS over TLS Test with server cert ----------*/


All these sections look very similar, maybe adding a function with config parameter could reduce code duplicaiton?

david-cermak · 2025-03-25T12:40:31Z

components/esp_dns/esp_dns_utils.h

+size_t create_dns_query(uint8_t *buffer, size_t buffer_size, const char *hostname, int addrtype, uint16_t *id_o);
+
+/* Function to parse a DNS answer for an A and AAAA records */
+void parse_dns_response(uint8_t *buffer, size_t response_size, dns_response_t *dns_response);


would also suggest namespacing these. Even if this is a private header, the symbol would still reside in global symbol name and may cause collision.

david-cermak · 2025-03-25T12:43:24Z

components/esp_dns/esp_dns_utils.c

+    uint8_t offset = 0;
+
+    /* Loop through each part of the name, handling labels and compression pointers */
+    while (ptr[offset] != 0) {


should we also check if wer'e not past the parsed data? (you can receive anything from the network, e.g. a malicious packet)?

david-cermak · 2025-03-25T12:46:08Z

components/esp_dns/esp_dns_doh.c

+#include "lwip/prot/dns.h"
+#include "lwip/api.h"
+#include "lwip/opt.h"
+#include "lwip/dns.h"


can we remove lwip dependency here?

david-cermak · 2025-03-25T12:46:37Z

components/esp_dns/esp_dns_doh.c

+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include "freertos/FreeRTOS.h"


also , do we need freertos in this module?

david-cermak · 2025-03-25T12:48:58Z

components/esp_dns/esp_dns.c

+    case DNS_PROTOCOL_TCP:
+        *err = dns_resolve_tcp(g_dns_handle, name, addr, rrtype);
+        break;
+    case DNS_PROTOCOL_DOT:
+        *err = dns_resolve_dot(g_dns_handle, name, addr, rrtype);
+        break;


Question, can we use the factory design pattern here? (e.g. if a user wants DNS over TCP, they don't need to pull mbedtls into the link dependency)

Expose all the init function and remove the common init.

alisitsyn · 2025-03-26T10:28:49Z

components/esp_dns/esp_dns_doh.c

+                               &handle->response_buffer.dns_response);
+        } else {
+            ESP_LOGE(TAG, "HTTP Error: %d", esp_http_client_get_status_code(evt->client));
+            ESP_LOG_BUFFER_HEXDUMP(TAG, handle->response_buffer.buffer, handle->response_buffer.length, ESP_LOG_ERROR);


Just a question: In case of error response should the handle->response_buffer.buffer and handle->response_buffer.length be checked for correctness before print the buffer here?

euripedesrocha · 2025-03-24T09:54:33Z

components/esp_dns/include/esp_dns.h

+typedef struct dns_handle* esp_dns_handle_t;
+
+
+esp_dns_handle_t esp_dns_init(const esp_dns_config_t *config);


Missing documentation.

euripedesrocha · 2025-03-27T08:13:40Z

components/esp_dns/CMakeLists.txt

+                    PRIV_INCLUDE_DIRS "."
+                    PRIV_REQUIRES nvs_flash lwip esp_event esp-tls esp_http_client esp-tls tcp_transport)
+
+if(CONFIG_LWIP_HOOK_NETCONN_EXT_RESOLVE_CUSTOM)


Isn't this required for this component to work? We should add an error in case it is not enabled.

Add a warning that the hook is not enabled.

euripedesrocha · 2025-03-27T08:17:17Z

components/esp_dns/README.md

+- [Features](#features)
+- [How It Works](#how-it-works)
+- [Certificate Options](#certificate-options)
+- [How to Use](#how-to-use)
+- [Configuration](#configuration)
+- [Common DNS Servers](#common-dns-servers)
+- [Requirements](#requirements)
+- [Limitations](#limitations)
+- [Performance Considerations](#performance-considerations)
+- [Troubleshooting](#troubleshooting)


Suggested change

- [Features](#features)

- [How It Works](#how-it-works)

- [Certificate Options](#certificate-options)

- [How to Use](#how-to-use)

- [Configuration](#configuration)

- [Common DNS Servers](#common-dns-servers)

- [Requirements](#requirements)

- [Limitations](#limitations)

- [Performance Considerations](#performance-considerations)

- [Troubleshooting](#troubleshooting)

- [Features](#features)

- [Requirements](#requirements)

- [How to Use](#how-to-use)

- [Configuration](#configuration)

- [Certificate Options](#certificate-options)

- [Common DNS Servers](#common-dns-servers)

- [Limitations](#limitations)

- [Performance Considerations](#performance-considerations)

- [How It Works](#how-it-works)

- [Troubleshooting](#troubleshooting)

Reorder the outline for a better reading flow.

euripedesrocha · 2025-03-27T08:21:47Z

components/esp_dns/README.md

+
+### 1. Add Component to Your Project
+
+Add the ESP DNS component to your project's `components` directory or include it as a dependency in your project's `idf_component.yml` file.


Also, this README also appear in the component manager so this information is already presented to user. This section is useful only if the user is reading it out of the component manager page.

euripedesrocha · 2025-03-27T08:23:38Z

components/esp_dns/esp_dns.c

+#include "freertos/semphr.h"
+#include "freertos/task.h"
+#include "esp_log.h"
+//#include "esp_netif.h"


euripedesrocha · 2025-03-27T08:44:02Z

components/esp_dns/esp_dns_dot.c

+    if (handle->config.tls_config.crt_bundle_attach) {
+        esp_transport_ssl_crt_bundle_attach(transport, handle->config.tls_config.crt_bundle_attach);
+    } else {
+        if (handle->config.tls_config.cert_pem == NULL) {


Add support for DER

euripedesrocha · 2025-03-27T08:47:31Z

components/esp_dns/esp_dns_dot.c

+    }
+
+    /* Send DNS query */
+    len = esp_transport_write(transport,


Shouldn't we iterate to guarantee that the whole buffer was sent?

euripedesrocha · 2025-03-27T08:51:40Z

components/esp_dns/esp_dns_dot.c

+                             sizeof(dot_buffer),
+                             timeout_ms);
+    if (len > 0) {
+        /* Skip the 2-byte length field that prepends DNS messages as required by RFC 7858 */


The 2 bytes encode the size of the answer. It would be better to use it to guide the parsing and allow processing of bigger answer and future memory usage control.

euripedesrocha · 2025-03-27T08:54:10Z

components/esp_dns/esp_dns_priv.h

+    /* Cache management. TBD: Not implemented yet */
+    struct {
+        void *cache;                   /* DNS cache structure */
+        uint64_t last_cleanup;         /* Timestamp of last cache cleanup */
+    } cache_state;
+
+    /* Statistics. TBD: Not implemented yet */
+    struct {
+        uint64_t queries_sent;         /* Total number of queries sent */
+        uint64_t successful_responses; /* Total number of successful responses */
+        uint64_t timeouts;             /* Number of query timeouts */
+        uint64_t errors;               /* Number of query errors */
+        uint64_t fallbacks;            /* Number of protocol fallbacks */
+        uint64_t cache_hits;           /* Number of cache hits */
+        double avg_response_time_ms;   /* Average response time in milliseconds */
+    } stats;


If not implemented, we should remove it from the MR and create a task to track it.

euripedesrocha · 2025-03-27T08:55:37Z

components/esp_dns/esp_dns_udp.c

+/* DNS resolution functions for different transport types */
+err_t dns_resolve_udp(const esp_dns_handle_t handle, const char *name, ip_addr_t *addr, u8_t rrtype)
+{
+    // TODO: Implement UDP DNS resolution


Will you add it in this MR? If not, it should be removed from the feature list in the README.

alisitsyn · 2025-03-27T09:17:55Z

components/esp_dns/esp_dns_utils.c

+    0x00, 0x01        // QCLASS: IN (internet)
+    */
+
+    dns_header_t *header = (dns_header_t *)buffer;


Here and below: Is it better to check pointers before using?

alisitsyn · 2025-03-27T09:43:21Z

components/esp_dns/examples/esp_dns_basic/main/esp_dns_example.c

+#include "esp_crt_bundle.h"
+#endif
+
+#define ENABLE_NATIVE_UDP 1


Can these values be defined in kconfig?

alisitsyn · 2025-03-27T11:39:56Z

components/esp_dns/README.md

+
+## Configuration
+
+###Setting Up the ESP DNS Component


Minor: add a space before Setting to show it properly

alisitsyn · 2025-03-27T12:00:24Z

components/esp_dns/examples/esp_dns_basic/pytest_esp_dns.py

+def test_examples_getaddrinfo(dut):
+    dut.expect('esp>', timeout=30)
+    dut.write('getaddrinfo www.google.com')
+    dut.expect(r'getaddrinfo', timeout=30)


I am thinking if it is better to catch more information about resolved addresses using regular expressions?

espressif-abhikroy self-assigned this Mar 14, 2025

espressif-abhikroy force-pushed the component/esp_dns branch 5 times, most recently from 5a245b4 to f575341 Compare March 21, 2025 12:57

espressif-abhikroy force-pushed the component/esp_dns branch from f575341 to 78cf2bc Compare March 21, 2025 12:58

espressif-abhikroy marked this pull request as ready for review March 21, 2025 12:59

espressif-abhikroy requested review from euripedesrocha, glmfe, alisitsyn, david-cermak and kostaond March 21, 2025 13:01

david-cermak reviewed Mar 25, 2025

View reviewed changes

alisitsyn reviewed Mar 26, 2025

View reviewed changes

euripedesrocha reviewed Mar 27, 2025

View reviewed changes

alisitsyn reviewed Mar 27, 2025

View reviewed changes

		\| Supported Targets \| ESP32 \| ESP32-C2 \| ESP32-C3 \| ESP32-C5 \| ESP32-C6 \| ESP32-C61 \| ESP32-H2 \| ESP32-P4 \| ESP32-S2 \| ESP32-S3 \|
		\| ----------------- \| ----- \| -------- \| -------- \| -------- \| -------- \| --------- \| -------- \| -------- \| -------- \| -------- \|


		- 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.


		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, such as the OpenThread component.


		### 1. Add Component to Your Project

		Add the ESP DNS component to your project's `components` directory or include it as a dependency in your project's `idf_component.yml` file.



		/* Global DNS handle instance */
		static esp_dns_handle_t g_dns_handle = NULL;

	static esp_dns_handle_t g_dns_handle = NULL;
	static esp_dns_handle_t s_dns_handle = NULL;

		static struct dns_handle instance;
		static bool initialized = false;


		/* ========================= LWIP HOOK FUNCTIONS ========================= */

		#if defined(CONFIG_LWIP_HOOK_NETCONN_EXT_RESOLVE_CUSTOM)

		typedef struct dns_handle* esp_dns_handle_t;


		esp_dns_handle_t esp_dns_init(const esp_dns_config_t *config);

feat(common): Add ESP DNS module with support for UDP, DoT, and DoH protocols #781

Are you sure you want to change the base?

feat(common): Add ESP DNS module with support for UDP, DoT, and DoH protocols #781

Conversation

espressif-abhikroy commented Mar 14, 2025 • edited Loading

Description

Related

Testing

Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

david-cermak left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alisitsyn Mar 27, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

espressif-abhikroy commented Mar 14, 2025 •

edited

Loading

alisitsyn Mar 27, 2025 •

edited

Loading