mirror of
https://github.com/espressif/esp-protocols.git
synced 2025-11-03 08:01:42 +01:00
57cd60807e
This commit introduces a custom DNS module for ESP32, enabling DNS resolution capabilities over various protocols including UDP, TCP, DNS over TLS (DoT), and DNS over HTTPS (DoH). The module includes initialization and cleanup functionalities, along with protocol-specific implementations for each DNS type.
156 lines
4.9 KiB
C
156 lines
4.9 KiB
C
/*
|
|
* SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
|
|
*
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
#pragma once
|
|
|
|
#include "sdkconfig.h"
|
|
#include "esp_err.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#define ESP_DNS_DEFAULT_TCP_PORT 53 /* Default TCP port for DNS */
|
|
#define ESP_DNS_DEFAULT_DOT_PORT 853 /* Default TLS port for DNS over TLS */
|
|
#define ESP_DNS_DEFAULT_DOH_PORT 443 /* Default HTTPS port for DNS over HTTPS */
|
|
|
|
#define ESP_DNS_DEFAULT_TIMEOUT_MS 10000 /* Default timeout for DNS queries in milliseconds */
|
|
|
|
typedef enum {
|
|
ESP_DNS_PROTOCOL_UDP, /* Traditional UDP DNS (Port 53) */
|
|
ESP_DNS_PROTOCOL_TCP, /* TCP DNS (Port 53) */
|
|
ESP_DNS_PROTOCOL_DOT, /* DNS over TLS (Port 853) */
|
|
ESP_DNS_PROTOCOL_DOH, /* DNS over HTTPS (Port 443) */
|
|
} esp_dns_protocol_type_t;
|
|
|
|
/**
|
|
* @brief DNS configuration structure
|
|
*/
|
|
typedef struct {
|
|
/* Basic protocol selection */
|
|
esp_dns_protocol_type_t protocol; /* DNS protocol type */
|
|
|
|
/* Common settings */
|
|
const char *dns_server; /* DNS server IP address or hostname */
|
|
uint16_t port; /* Custom port number (if not using default) */
|
|
uint32_t timeout_ms; /* Query timeout in milliseconds */
|
|
|
|
/* Secure protocol options */
|
|
struct {
|
|
const char *cert_pem; /* SSL server certification in PEM format as string */
|
|
esp_err_t (*crt_bundle_attach)(void *conf); /* Function pointer to attach cert bundle */
|
|
} tls_config; /* Used for DoT, DoH, DoH3, DNSCrypt, DoQ */
|
|
|
|
/* Protocol-specific options */
|
|
union {
|
|
/* DoH options */
|
|
struct {
|
|
const char *url_path; /* URL path for DoH service (e.g., "/dns-query") */
|
|
} doh_config; /* DNS over HTTPS configuration */
|
|
} protocol_config; /* Protocol-specific configuration */
|
|
} esp_dns_config_t;
|
|
|
|
typedef struct esp_dns_handle* esp_dns_handle_t;
|
|
|
|
/**
|
|
* @brief Initialize DNS over HTTPS (DoH) module
|
|
*
|
|
* Sets up the DoH service using the provided configuration. Validates the parameters,
|
|
* sets the protocol, and initializes the DNS module.
|
|
*
|
|
* @param config Pointer to the DNS configuration structure
|
|
*
|
|
* @return Handle to the initialized DoH module on success, NULL on failure
|
|
*/
|
|
esp_dns_handle_t esp_dns_init_doh(esp_dns_config_t *config);
|
|
|
|
/**
|
|
* @brief Initialize DNS over TLS (DoT) module
|
|
*
|
|
* Sets up the DoT service using the provided configuration. Validates the parameters,
|
|
* sets the protocol, and initializes the DNS module.
|
|
*
|
|
* @param config Pointer to the DNS configuration structure
|
|
*
|
|
* @return Handle to the initialized DoT module on success, NULL on failure
|
|
*/
|
|
esp_dns_handle_t esp_dns_init_dot(esp_dns_config_t *config);
|
|
|
|
/**
|
|
* @brief Initialize TCP DNS module
|
|
*
|
|
* Sets up the TCP DNS service using the provided configuration. Validates the parameters,
|
|
* sets the protocol, and initializes the DNS module.
|
|
*
|
|
* @param config Pointer to the DNS configuration structure
|
|
*
|
|
* @return Handle to the initialized TCP module on success, NULL on failure
|
|
*/
|
|
esp_dns_handle_t esp_dns_init_tcp(esp_dns_config_t *config);
|
|
|
|
/**
|
|
* @brief Initialize UDP DNS module
|
|
*
|
|
* Sets up the UDP DNS service using the provided configuration. Validates the parameters,
|
|
* sets the protocol, and initializes the DNS module.
|
|
*
|
|
* @param config Pointer to the DNS configuration structure
|
|
*
|
|
* @return Handle to the initialized UDP module on success, NULL on failure
|
|
*/
|
|
esp_dns_handle_t esp_dns_init_udp(esp_dns_config_t *config);
|
|
|
|
/**
|
|
* @brief Clean up DNS over HTTPS (DoH) module
|
|
*
|
|
* Releases resources allocated for the DoH service. Validates the parameters,
|
|
* checks the protocol, and cleans up the DNS module.
|
|
*
|
|
* @param handle Pointer to the DNS handle to be cleaned up
|
|
*
|
|
* @return 0 on success, -1 on failure
|
|
*/
|
|
int esp_dns_cleanup_doh(esp_dns_handle_t handle);
|
|
|
|
/**
|
|
* @brief Clean up DNS over TLS (DoT) module
|
|
*
|
|
* Releases resources allocated for the DoT service. Validates the parameters,
|
|
* checks the protocol, and cleans up the DNS module.
|
|
*
|
|
* @param handle Pointer to the DNS handle to be cleaned up
|
|
*
|
|
* @return 0 on success, -1 on failure
|
|
*/
|
|
int esp_dns_cleanup_dot(esp_dns_handle_t handle);
|
|
|
|
/**
|
|
* @brief Clean up TCP DNS module
|
|
*
|
|
* Releases resources allocated for the TCP DNS service. Validates the parameters,
|
|
* checks the protocol, and cleans up the DNS module.
|
|
*
|
|
* @param handle Pointer to the DNS handle to be cleaned up
|
|
*
|
|
* @return 0 on success, -1 on failure
|
|
*/
|
|
int esp_dns_cleanup_tcp(esp_dns_handle_t handle);
|
|
|
|
/**
|
|
* @brief Clean up UDP DNS module
|
|
*
|
|
* Releases resources allocated for the UDP DNS service. Validates the parameters,
|
|
* checks the protocol, and cleans up the DNS module.
|
|
*
|
|
* @param handle Pointer to the DNS handle to be cleaned up
|
|
*
|
|
* @return 0 on success, -1 on failure
|
|
*/
|
|
int esp_dns_cleanup_udp(esp_dns_handle_t handle);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|