lws-async-dns.h

Go to the documentation of this file.

/*
 * libwebsockets - small server side websockets and web server implementation
 *
 * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to
 * deal in the Software without restriction, including without limitation the
 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 * sell copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 * IN THE SOFTWARE.
 */
 
#if defined(LWS_WITH_UDP) && defined(LWS_WITH_NETWORK)
 
typedef enum dns_query_type {
        LWS_ADNS_RECORD_A                                       = 0x01,
        LWS_ADNS_RECORD_CNAME                                   = 0x05,
        LWS_ADNS_RECORD_SOA                                     = 0x06,
        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,
        LWS_ADNS_RECORD_HTTPS                                   = 0x41,
 
        /*
         * Query types are combined by OR with the flag bits defined below
         * the enum (LWS_ADNS_SYNTHETIC .. LWS_ADNS_IGNORE_HOSTS_FILE; the
         * largest possible combination is 0x1f0041).  A C enum can only
         * hold values within the range of its listed constants, so this
         * sentinel extends the enum's range over the whole flag space...
         * without it, any OR'd combination is undefined behaviour, which
         * -fsanitize=enum trips on.
         */
 
        LWS_ADNS_RECORD_TYPE_AND_FLAGS_MAX                      = 0x1f0041,
} adns_query_type_t;
 
typedef enum {
        LADNS_RET_FAILED_WSI_CLOSED                             = -4,
        LADNS_RET_NXDOMAIN                                      = -3,
        LADNS_RET_TIMEDOUT                                      = -2,
        LADNS_RET_FAILED                                        = -1,
        LADNS_RET_FOUND,
        LADNS_RET_CONTINUING
} lws_async_dns_retcode_t;
 
/*
 * The values are those lws_system_ops_t .async_dns_dnssec_mode documents.
 * Before 2026-10 REQUIRE and TOLERATE were the other way around (1 was
 * TOLERATE), so binaries built against older headers that use the enum names
 * now get the other mode: rebuild them.
 */
typedef enum {
        LWS_ADNS_DNSSEC_OFF             = 0,
        LWS_ADNS_DNSSEC_REQUIRE         = 1,
        LWS_ADNS_DNSSEC_TOLERATE        = 2,
} 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 */
#define LWS_ADNS_NOCACHE                0x40000 /* force network query, bypass cache */
#define LWS_ADNS_WANT_DNSSEC    0x80000 /* Explicitly set DO bit in EDNS0 OPT record */
#define LWS_ADNS_IGNORE_HOSTS_FILE 0x100000 /* Bypass checking /etc/hosts and force network DNS lookup */
#define LADNS_NO_WSI_BUT_OK ((struct lws *)(intptr_t)0x1)
 
struct addrinfo;
 
/*
 * The completion callback: ads is the name the lookup was asked for, whatever
 * CNAME or search list domain it was resolved through; result is the addrinfo
 * chain to release with lws_async_dns_freeaddrinfo(), or NULL; n is the
 * lws_async_dns_retcode_t, or'd with LWS_ADNS_DNSSEC_VALID if validated
 */
typedef struct lws * (*lws_async_dns_cb_t)(struct lws *wsi, const char *ads,
                const struct addrinfo *result, int n, void *opaque);
 
struct lws_adns_q;
struct lws_async_dns;
struct lws_async_dns_server;

LWS_VISIBLE LWS_EXTERN lws_async_dns_retcode_t
lws_async_dns_query(struct lws_context *context, int tsi, const char *name,
                    adns_query_type_t qtype, lws_async_dns_cb_t cb,
                    struct lws *wsi, void *opaque, struct lws_adns_q **pq);

LWS_VISIBLE LWS_EXTERN void
lws_async_dns_cancel_by_opaque(struct lws_context *context, void *opaque);

LWS_VISIBLE LWS_EXTERN void
lws_async_dns_freeaddrinfo(const struct addrinfo **ai);

LWS_VISIBLE LWS_EXTERN const uint8_t *
lws_async_dns_get_rr_cache(struct lws_context *context, const char *name,
                           adns_query_type_t qtype, uint16_t *paylen);

LWS_VISIBLE LWS_EXTERN int
lws_async_dns_get_alpn(struct lws_context *context, const char *name, const char *alpn);

typedef struct lws_adns_direct_rr {
        const uint8_t           *rdata;
        uint32_t                ttl;
        uint16_t                type;
        uint16_t                len;
} lws_adns_direct_rr_t;
 
#define LWS_ADNS_DIRECT_MAX_RRS         16

typedef struct lws_adns_direct_result {
        lws_async_dns_retcode_t         ret;
        uint8_t                         rcode;
        uint8_t                         authoritative;
        const lws_adns_direct_rr_t      *rrs;
        int                             count;
} lws_adns_direct_result_t;
 
typedef void (*lws_async_dns_direct_cb_t)(void *opaque,
                                          const lws_adns_direct_result_t *r);
 
struct lws_adns_direct;

LWS_VISIBLE LWS_EXTERN struct lws_adns_direct *
lws_async_dns_query_direct(struct lws_context *context,
                           const lws_sockaddr46 *server, const char *name,
                           adns_query_type_t qtype,
                           lws_async_dns_direct_cb_t cb, void *opaque);

LWS_VISIBLE LWS_EXTERN void
lws_async_dns_query_direct_cancel(struct lws_adns_direct **pd);

LWS_VISIBLE LWS_EXTERN int
lws_async_dns_server_add(struct lws_context *cx, const lws_sockaddr46 *sa46);

LWS_VISIBLE LWS_EXTERN void
lws_async_dns_server_remove(struct lws_context *cx, const lws_sockaddr46 *sa46);
 
/* only needed for testing */
 
/* the tid of q's A question, or of its only question if not an address */
LWS_VISIBLE LWS_EXTERN uint16_t
lws_adns_get_tid(struct lws_adns_q *q);
/* the tid of an address lookup's AAAA question */
LWS_VISIBLE LWS_EXTERN uint16_t
lws_adns_get_tid_aaaa(struct lws_adns_q *q);
LWS_VISIBLE LWS_EXTERN struct lws_async_dns *
lws_adns_get_async_dns(struct lws_adns_q *q);
 
LWS_VISIBLE LWS_EXTERN struct lws_async_dns_server *
lws_adns_get_server(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,
                   struct lws_async_dns_server *dsrv);

LWS_VISIBLE LWS_EXTERN int
lws_plat_asyncdns_get_server(struct lws_context *context, int n,
                             lws_sockaddr46 *sa46);

LWS_VISIBLE LWS_EXTERN int
lws_plat_asyncdns_get_search(struct lws_context *context, char *buf,
                             size_t len, int *ndots);

LWS_VISIBLE LWS_EXTERN int
lws_async_dns_server_reload(struct lws_context *context);
 

LWS_VISIBLE LWS_EXTERN void
lws_async_dns_dnssec_set_mode(struct lws_context *context, lws_async_dns_dnssec_mode_t mode);
 
/*
 * A DS record for the root zone's key signing key, ie, a DNSSEC trust anchor
 */
typedef struct lws_adns_ds_anchor {
        const uint8_t           *digest;
        size_t                  digest_len;
        uint16_t                key_tag;
        uint8_t                 algorithm;      /* eg, 8 = RSASHA256 */
        uint8_t                 digest_type;    /* 2 = SHA-256, 4 = SHA-384 */
} lws_adns_ds_anchor_t;

LWS_VISIBLE LWS_EXTERN int
lws_async_dns_dnssec_set_root_anchors(struct lws_context *context,
                                      const lws_adns_ds_anchor_t *anchors,
                                      size_t count);
 
#endif