dns_internal.h

Go to the documentation of this file.

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2015, Digium, Inc.
 *
 * Joshua Colp <[email protected]>
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */

/*! \file
 *
 * \brief Internal DNS structure definitions
 *
 * \author Joshua Colp <[email protected]>
 */

#ifndef _ASTERISK_DNS_INTERNAL_H
#define _ASTERISK_DNS_INTERNAL_H

/*! \brief For AST_LIST */
#include "asterisk/linkedlists.h"

/*! \brief For AST_VECTOR */
#include "asterisk/vector.h"

/*! \brief For ast_dns_query_set_callback */
#include "asterisk/dns_query_set.h"

/*! \brief Generic DNS record information */
struct ast_dns_record {
   /*! \brief Resource record type */
   int rr_type;
   /*! \brief Resource record class */
   int rr_class;
   /*! \brief Time-to-live of the record */
   int ttl;
   /*! \brief The size of the raw DNS record */
   size_t data_len;
   /*! \brief Linked list information */
   AST_LIST_ENTRY(ast_dns_record) list;
   /*! \brief pointer to record-specific data.
    *
    * For certain "subclasses" of DNS records, the
    * location of the raw DNS data will differ from
    * the generic case. This pointer will reliably
    * be set to point to the raw DNS data, no matter
    * where in the structure it may lie.
    */
   char *data_ptr;
   /*! \brief The raw DNS record */
   char data[0];
};

/*! \brief A TXT record */
struct ast_dns_txt_record {
   /*! \brief Generic DNS record information */
   struct ast_dns_record generic;
   /*! \brief The number of character strings in the TXT record */
   size_t count;
   /*! \brief The raw DNS record */
   char data[0];
};

/*! \brief An SRV record */
struct ast_dns_srv_record {
   /*! \brief Generic DNS record information */
   struct ast_dns_record generic;
   /*! \brief The hostname in the SRV record */
   const char *host;
   /*! \brief The priority of the SRV record */
   unsigned short priority;
   /*! \brief The weight of the SRV record */
   unsigned short weight;
   /*! \brief The port in the SRV record */
   unsigned short port;
   /*! \brief The running weight sum */
   unsigned int weight_sum;
   /*! \brief Additional data */
   char data[0];
};

/*! \brief A NAPTR record */
struct ast_dns_naptr_record {
   /*! \brief Generic DNS record information */
   struct ast_dns_record generic;
   /*! \brief The flags from the NAPTR record */
   const char *flags;
   /*! \brief The service from the NAPTR record */
   const char *service;
   /*! \brief The regular expression from the NAPTR record */
   const char *regexp;
   /*! \brief The replacement from the NAPTR record */
   const char *replacement;
   /*! \brief The order for the NAPTR record */
   unsigned short order;
   /*! \brief The preference of the NAPTR record */
   unsigned short preference;
   /*! \brief Buffer for NAPTR-specific data
    *
    * This includes the raw NAPTR record, as well as
    * the area where the flags, service, regexp, and
    * replacement strings are stored.
    */
   char data[0];
};

/*! \brief The result of a DNS query */
struct ast_dns_result {
   /*! \brief Whether the result is secure */
   unsigned int secure;
   /*! \brief Whether the result is bogus */
   unsigned int bogus;
   /*! \brief Optional rcode, set if an error occurred */
   unsigned int rcode;
   /*! \brief Records returned */
   AST_LIST_HEAD_NOLOCK(dns_records, ast_dns_record) records;
   /*! \brief The canonical name */
   const char *canonical;
   /*! \brief The raw DNS answer */
   const char *answer;
   /*! \brief The size of the raw DNS answer */
   size_t answer_size;
   /*! \brief Buffer for dynamic data */
   char buf[0];
};

/*! \brief A DNS query */
struct ast_dns_query {
   /*! \brief Callback to invoke upon completion */
   ast_dns_resolve_callback callback;
   /*! \brief User-specific data */
   void *user_data;
   /*! \brief The resolver in use for this query */
   struct ast_dns_resolver *resolver;
   /*! \brief Resolver-specific data */
   void *resolver_data;
   /*! \brief Result of the DNS query */
   struct ast_dns_result *result;
   /*! \brief Resource record type */
   int rr_type;
   /*! \brief Resource record class */
   int rr_class;
   /*! \brief The name of what is being resolved */
   char name[0];
};

/*! \brief A recurring DNS query */
struct ast_dns_query_recurring {
   /*! \brief Callback to invoke upon completion */
   ast_dns_resolve_callback callback;
   /*! \brief User-specific data */
   void *user_data;
   /*! \brief Current active query */
   struct ast_dns_query_active *active;
   /*! \brief The recurring query has been cancelled */
   unsigned int cancelled;
   /*! \brief Scheduled timer for next resolution */
   int timer;
   /*! \brief Resource record type */
   int rr_type;
   /*! \brief Resource record class */
   int rr_class;
   /*! \brief The name of what is being resolved */
   char name[0];
};

/*! \brief A DNS query set query, which includes its state */
struct dns_query_set_query {
   /*! \brief Whether the query started successfully or not */
   unsigned int started;
   /*! \brief The query itself */
   struct ast_dns_query *query;
};

/*! \brief A set of DNS queries */
struct ast_dns_query_set {
   /*! \brief DNS queries */
   AST_VECTOR(, struct dns_query_set_query) queries;
   /*! \brief Whether the query set is in progress or not */
   int in_progress;
   /*! \brief The total number of completed queries */
   int queries_completed;
   /*! \brief The total number of cancelled queries */
   int queries_cancelled;
   /*! \brief Callback to invoke upon completion */
   ast_dns_query_set_callback callback;
   /*! \brief User-specific data */
   void *user_data;
};

/*! \brief An active DNS query */
struct ast_dns_query_active {
   /*! \brief The underlying DNS query */
   struct ast_dns_query *query;
};

struct ast_sched_context;

/*!
 * \brief Retrieve the DNS scheduler context
 *
 * \return scheduler context
 */
struct ast_sched_context *ast_dns_get_sched(void);

/*!
 * \brief Allocate and parse a DNS TXT record
 * \since 16.10.0, 17.4.0
 *
 * \param query The DNS query
 * \param data This specific TXT record
 * \param size The size of the TXT record
 *
 * \retval non-NULL success
 * \retval NULL failure
 */
struct ast_dns_record *dns_txt_alloc(struct ast_dns_query *query, const char *data, const size_t size);

/*!
 * \brief Allocate and parse a DNS NAPTR record
 *
 * \param query The DNS query
 * \param data This specific NAPTR record
 * \param size The size of the NAPTR record
 *
 * \retval non-NULL success
 * \retval NULL failure
 */
struct ast_dns_record *dns_naptr_alloc(struct ast_dns_query *query, const char *data, const size_t size);

/*!
 * \brief Sort the NAPTR records on a result
 *
 * \param result The DNS result
 */
void dns_naptr_sort(struct ast_dns_result *result);

/*!
 * \brief Allocate and parse a DNS SRV record
 *
 * \param query The DNS query
 * \param data This specific SRV record
 * \param size The size of the SRV record
 *
 * \retval non-NULL success
 * \retval NULL failure
 */
struct ast_dns_record *dns_srv_alloc(struct ast_dns_query *query, const char *data, const size_t size);

/*!
 * \brief Sort the SRV records on a result
 *
 * \param result The DNS result
 */
void dns_srv_sort(struct ast_dns_result *result);

/*!
 * \brief Find the location of a DNS record within the entire DNS answer
 *
 * The DNS record that has been returned by the resolver may be a copy of the record that was
 * found in the complete DNS response. If so, then some DNS record types (specifically those that
 * parse domains) will need to locate the DNS record within the complete DNS response. This is so
 * that if the domain contains pointers to other sections of the DNS response, then the referenced
 * domains may be located.
 *
 * \param record The DNS record returned by a resolver implementation
 * \param record_size The size of the DNS record in bytes
 * \param response The complete DNS answer
 * \param response_size The size of the complete DNS response
 */
char *dns_find_record(const char *record, size_t record_size, const char *response, size_t response_size);

/*!
 * \brief Parse a 16-bit unsigned value from a DNS record
 *
 * \param cur Pointer to the location of the 16-bit value in the DNS record
 * \param[out] val The parsed 16-bit unsigned integer
 * \return The number of bytes consumed while parsing
 */
int dns_parse_short(unsigned char *cur, uint16_t *val);

/*!
 * \brief Parse a DNS string from a DNS record
 *
 * A DNS string consists of an 8-bit size, followed by the
 * string value (not NULL-terminated).
 *
 * \param cur Pointer to the location of the DNS string
 * \param[out] size The parsed size of the DNS string
 * \param[out] val The contained string (not NULL-terminated)
 * \return The number of bytes consumed while parsing
 */
int dns_parse_string(char *cur, uint8_t *size, char **val);

/*!
 * \brief Allocate a DNS query (but do not start resolution)
 *
 * \param name The name of what to resolve
 * \param rr_type Resource record type
 * \param rr_class Resource record class
 * \param callback The callback to invoke upon completion
 * \param data User data to make available on the query
 *
 * \retval non-NULL success
 * \retval NULL failure
 *
 * \note The result passed to the callback does not need to be freed
 *
 * \note The user data MUST be an ao2 object
 *
 * \note This function increments the reference count of the user data, it does NOT steal
 *
 * \note The query must be released upon completion or cancellation using ao2_ref
 */
struct ast_dns_query *dns_query_alloc(const char *name, int rr_type, int rr_class, ast_dns_resolve_callback callback, void *data);

#endif /* _ASTERISK_DNS_INTERNAL_H */