async_dns: DNSSEC

p

Author: lws-team

CMakeLists-implied-options.txt

@@ -426,6 +426,11 @@ if (LWS_WITH_AUTHORITATIVE_DNS)
 	set(LWS_WITH_JOSE 1)
 endif()
 
+if (LWS_WITH_SYS_ASYNC_DNS_DNSSEC)
+	set(LWS_WITH_SYS_ASYNC_DNS 1)
+	set(LWS_WITH_GENCRYPTO 1)
+endif()
+
 # using any abstract protocol enables LWS_WITH_ABSTRACT
 
 #if (LWS_WITH_SMTP)

CMakeLists.txt

@@ -176,6 +176,7 @@ option(LWS_WITH_ALEXA "Enable Alexa example" OFF)
 option(LWS_WITH_GTK "Enable gtk example" OFF)
 option(LWS_WITH_FTS "Full Text Search support" OFF)
 option(LWS_WITH_SYS_ASYNC_DNS "Nonblocking internal IPv4 + IPv6 DNS resolver" OFF)
+option(LWS_WITH_SYS_ASYNC_DNS_DNSSEC "Include DNSSEC parsing/validation in async-dns (requires crypto)" OFF)
 option(LWS_WITH_AUTHORITATIVE_DNS "Authoritative DNS zone signer" OFF)
 option(LWS_WITH_SYS_NTPCLIENT "Build in tiny ntpclient good for tls date validation and run via lws_system" OFF)
 option(LWS_WITH_SYS_DHCP_CLIENT "Build in tiny DHCP client" OFF)

READMEs/README.async-dns.md

@@ -97,4 +97,17 @@ and restarts it.  It allows this to happen for 3 CNAME deep.
 At the end, either way, the cached result is set using the original
 query name and the results from the last CNAME in the chain.
 
+## DNSSEC Support
+
+Async DNS supports DNSSEC validation of responses. This is optional and provides robust protection against DNS spoofing or injection of forged results.
+
+To enable DNSSEC features, build with `-DLWS_WITH_SYS_ASYNC_DNS_DNSSEC=1` in CMake. This will automatically enable the `LWS_WITH_GENCRYPTO` required dependency.
+
+Once enabled, clients can strictly enforce DNSSEC validation globally via the config struct or explicitly over context:
+```c
+lws_async_dns_dnssec_set_mode(context, LWS_ADNS_DNSSEC_REQUIRE);
+```
+
+When validation is set to `LWS_ADNS_DNSSEC_REQUIRE`, queries failing to authenticate computationally with upstream Trust Anchors (or those lacking RRSIG/DNSKEY records entirely) will be explicitly rejected by the resolver and not propagate to callbacks or connections. But some domains inherently lack DNSSEC. For situations where strict DNSSEC is globally mandated, but a small handful of known-unsigned destinations must be reached, clients can explicitly set the `LWS_ADNS_INDICATE_LACKS_DNSSEC` bitflag natively on integer `qtype` lookups. This allows the resolver to tolerate missing records explicitly for that singular lookup, while strictly required globally.
+
 

cmake/lws_config.h.in

@@ -154,6 +154,7 @@
 #cmakedefine LWS_WITH_ALLOC_METADATA_LWS
 #cmakedefine LWS_WITH_ALSA
 #cmakedefine LWS_WITH_SYS_ASYNC_DNS
+#cmakedefine LWS_WITH_SYS_ASYNC_DNS_DNSSEC
 #cmakedefine LWS_WITH_AUTHORITATIVE_DNS
 #cmakedefine LWS_WITH_BORINGSSL
 #cmakedefine LWS_WITH_AWSLC

include/libwebsockets/lws-async-dns.h

@@ -28,7 +28,13 @@ typedef enum dns_query_type {
 	LWS_ADNS_RECORD_A					= 0x01,
 	LWS_ADNS_RECORD_CNAME					= 0x05,
 	LWS_ADNS_RECORD_MX					= 0x0f,
+	LWS_ADNS_RECORD_TXT					= 0x10,
 	LWS_ADNS_RECORD_AAAA					= 0x1c,
+	LWS_ADNS_RECORD_DS					= 0x2b,
+	LWS_ADNS_RECORD_RRSIG					= 0x2e,
+	LWS_ADNS_RECORD_NSEC					= 0x2f,
+	LWS_ADNS_RECORD_DNSKEY					= 0x30,
+	LWS_ADNS_RECORD_NSEC3					= 0x32,
 } adns_query_type_t;
 
 typedef enum {
@@ -40,8 +46,18 @@ typedef enum {
 	LADNS_RET_CONTINUING
 } lws_async_dns_retcode_t;
 
+typedef enum {
+	LWS_ADNS_DNSSEC_OFF = 0,
+	LWS_ADNS_DNSSEC_TOLERATE,
+	LWS_ADNS_DNSSEC_REQUIRE,
+} lws_async_dns_dnssec_mode_t;
+
+#define LWS_ADNS_DNSSEC_VALID	(1 << 8)
+#define LWS_ADNS_DNSSEC_INVALID	(1 << 9)
+
 #define LWS_ADNS_SYNTHETIC	0x10000	/* don't send, synthetic response will
 					 * be injected for testing */
+#define LWS_ADNS_INDICATE_LACKS_DNSSEC	0x20000 /* tolerate missing DNSSEC on this specific lookup */
 
 struct addrinfo;
 
@@ -127,4 +143,31 @@ lws_adns_get_async_dns(struct lws_adns_q *q);
 LWS_VISIBLE LWS_EXTERN void
 lws_adns_parse_udp(struct lws_async_dns *dns, const uint8_t *pkt, size_t len);
 
+/**
+ * lws_plat_asyncdns_get_server() - Get system DNS server address
+ *
+ * \param context: the lws_context
+ * \param n: the zero-based index of the server to get
+ * \param sa46: pointer to lws_sockaddr46 to receive the server address
+ *
+ * This platform-specific primitive allows retrieving the system's DNS
+ * configuration. It returns 0 if the `n`th nameserver is written to `sa46`,
+ * or < 0 if there is no `n`th nameserver available.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_plat_asyncdns_get_server(struct lws_context *context, int n,
+			     lws_sockaddr46 *sa46);
+
+
+/**
+ * lws_async_dns_dnssec_set_mode() - Set the system-wide DNSSEC mode
+ *
+ * \param context: the lws_context
+ * \param mode: the requested DNSSEC mode (off, tolerate, or require)
+ *
+ * Configures how the asynchronous DNS handles DNSSEC validation.
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_async_dns_dnssec_set_mode(struct lws_context *context, lws_async_dns_dnssec_mode_t mode);
+
 #endif

include/libwebsockets/lws-context-vhost.h

@@ -965,6 +965,7 @@ struct lws_context_creation_info {
 	 * server to forcibly add.  If given, the list of strings must be
 	 * terminated with a NULL.
 	 */
+
 #endif
 
 #if defined(WIN32)

include/libwebsockets/lws-system.h

@@ -232,6 +232,14 @@ typedef struct lws_system_ops {
 	uint32_t		wake_latency_us;
 	/**< time taken for this device to wake from suspend, in us
 	 */
+
+#if defined(LWS_WITH_SYS_ASYNC_DNS)
+	uint8_t			async_dns_dnssec_mode;
+	/**< 0: OFF, 1: REQUIRE, 2: TOLERATE */
+
+	const char		*async_dns_dnssec_trust_anchor;
+	/**< base64 DS record string serving as the root trust anchor */
+#endif
 } lws_system_ops_t;
 
 #if defined(LWS_WITH_SYS_STATE)

lib/core-net/private-lib-core-net.h

@@ -266,6 +266,8 @@ typedef struct lws_async_dns {
 	lws_dll2_owner_t	cached;
 
 	struct lws_context	*cx;
+
+	uint8_t			dnssec_mode; /* lws_async_dns_dnssec_mode_t */
 } lws_async_dns_t;
 
 #define lws_async_dns_from_server(_s) ((lws_async_dns_t *)_s->list.owner)

lib/core/context.c

@@ -1410,6 +1410,9 @@ lws_create_context(const struct lws_context_creation_info *info)
 	context->count_caps = info->count_caps;
 #endif
 
+#if defined(LWS_WITH_SYS_ASYNC_DNS)
+#endif
+
 
 #if defined(LWS_WITH_NETWORK)
 

lib/plat/freertos/freertos-resolv.c

@@ -26,25 +26,38 @@
 #include "private-lib-async-dns.h"
 
 #if defined(LWS_WITH_SYS_ASYNC_DNS)
-lws_async_dns_server_check_t
-lws_plat_asyncdns_init(struct lws_context *context, lws_async_dns_t *dns)
+int
+lws_plat_asyncdns_get_server(struct lws_context *context, int index,
+			     lws_sockaddr46 *sa46)
 {
-	lws_sockaddr46 sa46t;
 	uint32_t ipv4;
-	lws_async_dns_server_check_t s = LADNS_CONF_SERVER_SAME;
-	lws_async_dns_server_t *dsrv;
+
+	if (index > 0)
+		return -1;
 
 	FreeRTOS_GetAddressConfiguration(NULL, NULL, NULL, &ipv4);
 
-	memset(&sa46t, 0, sizeof(sa46t));
+	memset(sa46, 0, sizeof(*sa46));
+	sa46->sa4.sin_family = AF_INET;
+	sa46->sa4.sin_addr.s_addr = ipv4;
+
+	return 0;
+}
 
-	sa46t.sa4.sin_family = AF_INET;
-	sa46t.sa4.sin_addr.s_addr = ipv4;
+lws_async_dns_server_check_t
+lws_plat_asyncdns_init(struct lws_context *context, lws_async_dns_t *dns)
+{
+	lws_sockaddr46 sa46t;
+	lws_async_dns_server_check_t s = LADNS_CONF_SERVER_SAME;
+	lws_async_dns_server_t *dsrv;
+	int n = 0;
 
-	dsrv = __lws_async_dns_server_find(dns, &sa46t);
-	if (!dsrv) {
-		__lws_async_dns_server_add(dns, &sa46t);
-		s = LADNS_CONF_SERVER_CHANGED;
+	while (lws_plat_asyncdns_get_server(context, n++, &sa46t) == 0) {
+		dsrv = __lws_async_dns_server_find(dns, &sa46t);
+		if (!dsrv) {
+			__lws_async_dns_server_add(dns, &sa46t);
+			s = LADNS_CONF_SERVER_CHANGED;
+		}
 	}
 
 	return s;