DNS over DTLS sock API

Sock DNS over DTLS client. More...

Detailed Description

Sock DNS over DTLS client.

See also

RFC 8094

Warning

This feature is experimental!
This implementation is in an experimental state. RFC 8094 requires DNS over TLS (DoT) as a fall-back for the PMTU issues). This fallback is not in place in this implementation. Consequently, EDNS(0) to negotiate maximum response size is also not in place.

Modules
	DNS over DTLS compile-time configuration

Files
file	dodtls.h
	DNS over DTLS sock definitions.

Functions
int	sock_dodtls_query (const char *domain_name, void *addr_out, int family)
	Get IP address for DNS name.
int	sock_dodtls_get_server (sock_udp_ep_t *server)
	Get currently configured DNS over DTLS server endpoint.
sock_dtls_t *	sock_dodtls_get_dtls_sock (void)
	Return the sock used by the DNS over DTLS client.
sock_dtls_session_t *	sock_dodtls_get_server_session (void)
	Return the DTLS ssession used by the DNS over DTLS client.
int	sock_dodtls_set_server (const sock_udp_ep_t *server, const credman_credential_t *creds)
	Configure and establish session with DNS over DTLS server.

DNS over DTLS defines
#define	SOCK_DODTLS_PORT   (853)
	Default DNS over DTLS server port.
#define	CONFIG_SOCK_DODTLS_RETRIES   (2)
	Number of DNS over DTLS query retries.
#define	CONFIG_SOCK_DODTLS_TIMEOUT_MS   (1000U)
	Timeout for DNS over DTLS queries in milliseconds.

Macro Definition Documentation

CONFIG_SOCK_DODTLS_RETRIES

#define CONFIG_SOCK_DODTLS_RETRIES   (2)

Number of DNS over DTLS query retries.

Definition at line 54 of file dodtls.h.

CONFIG_SOCK_DODTLS_TIMEOUT_MS

#define CONFIG_SOCK_DODTLS_TIMEOUT_MS   (1000U)

Timeout for DNS over DTLS queries in milliseconds.

Definition at line 61 of file dodtls.h.

SOCK_DODTLS_PORT

#define SOCK_DODTLS_PORT   (853)

Default DNS over DTLS server port.

Definition at line 46 of file dodtls.h.

Function Documentation

sock_dodtls_get_dtls_sock()

sock_dtls_t * sock_dodtls_get_dtls_sock

(

void

)

Return the sock used by the DNS over DTLS client.

Returns

The sock used by the DNS over DTLS client

sock_dodtls_get_server()

int sock_dodtls_get_server

(

sock_udp_ep_t *

server

)

Get currently configured DNS over DTLS server endpoint.

Parameters

[out]

server

The currently configured DNS over DTLS server endpoint. May not be NULL on input.

Returns

0 if server was set.

-ENOTCONN, when currently no server is configured.

sock_dodtls_get_server_session()

sock_dtls_session_t * sock_dodtls_get_server_session

(

void

)

Return the DTLS ssession used by the DNS over DTLS client.

Returns

The DTLS session used by the DNS over DTLS client

sock_dodtls_query()

int sock_dodtls_query	(	const char *	domain_name,
		void *	addr_out,
		int	family
	)

Get IP address for DNS name.

This function will synchronously try to resolve a DNS A or AAAA record by contacting the DNS server specified in the global variable sock_dns_server.

By supplying AF_INET, AF_INET6 or AF_UNSPEC in family requesting of A records (IPv4), AAAA records (IPv6) or both can be selected.

This function will return the first DNS record it receives. IF both A and AAAA are requested, AAAA will be preferred.

Note

addr_out needs to provide space for any possible result! (4byte when family==AF_INET, 16byte otherwise)

Parameters

[in]	domain_name	DNS name to resolve into address
[out]	addr_out	buffer to write result into
[in]	family	Either AF_INET, AF_INET6 or AF_UNSPEC

Returns

the size of the resolved address on success

-ECONNREFUSED, when a DNS over DTLS server is not configured.

-ENOSPC, when the length of domain_name is greater than SOCK_DODTLS_MAX_NAME_LEN.

-EBADSG, when the DNS reply is not parseable.

sock_dodtls_set_server()

int sock_dodtls_set_server	(	const sock_udp_ep_t *	server,
		const credman_credential_t *	creds
	)

Configure and establish session with DNS over DTLS server.

Parameters

[in]	server	A DNS over DTLS server endpoint. May be NULL to destroy the session with and unset the currently configured server.
[in]	creds	DTLS credentials for the server (see (D)TLS Credential Manager). May be NULL, when server is also NULL.

Returns

0 on success.

-EINVAL, if cred contains invalid values.

-ENOSPC, if cred does not fit into (D)TLS Credential Manager.

Any other negative errno potentially returned by sock_udp_create(), sock_dtls_create(), sock_dtls_session_init() or sock_dtls_recv().