support/resolv_test.h

   1 /* DNS test framework and libresolv redirection.
   2    Copyright (C) 2016-2023 Free Software Foundation, Inc.
   3    This file is part of the GNU C Library.
   4
   5    The GNU C Library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Lesser General Public
   7    License as published by the Free Software Foundation; either
   8    version 2.1 of the License, or (at your option) any later version.
   9
  10    The GNU C Library is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13    Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser General Public
  16    License along with the GNU C Library; if not, see
  17    <https://www.gnu.org/licenses/>.  */
  18
  19 #ifndef SUPPORT_RESOLV_TEST_H
  20 #define SUPPORT_RESOLV_TEST_H
  21
  22 #include <arpa/nameser.h>
  23 #include <stdbool.h>
  24 #include <sys/cdefs.h>
  25
  26 __BEGIN_DECLS
  27
  28 /* Information about EDNS properties of a DNS query.  */
  29 struct resolv_edns_info
  30 {
  31   bool active;
  32   uint8_t extended_rcode;
  33   uint8_t version;
  34   uint16_t flags;
  35   uint16_t payload_size;
  36 };
  37
  38 /* This opaque struct collects information about the resolver testing
  39    currently in progress.  */
  40 struct resolv_test;
  41
  42 /* This struct provides context information when the response callback
  43    specified in struct resolv_redirect_config is invoked. */
  44 struct resolv_response_context
  45 {
  46   struct resolv_test *test;
  47   void *client_address;
  48   size_t client_address_length;
  49   unsigned char *query_buffer;
  50   size_t query_length;
  51   int server_index;
  52   bool tcp;
  53   struct resolv_edns_info edns;
  54 };
  55
  56 /* Produces a deep copy of the context.  */
  57 struct resolv_response_context *
  58   resolv_response_context_duplicate (const struct resolv_response_context *);
  59
  60 /* Frees the copy.  For the context passed to the response function,
  61    this happens implicitly.  */
  62 void resolv_response_context_free (struct resolv_response_context *);
  63
  64 /* This opaque struct is used to construct responses from within the
  65    response callback function.  */
  66 struct resolv_response_builder;
  67
  68 enum
  69   {
  70     /* Maximum number of test servers supported by the framework.  */
  71     resolv_max_test_servers = 3,
  72   };
  73
  74 /* Configuration settings specific to individual test servers.  */
  75 struct resolv_redirect_server_config
  76 {
  77   bool disable_tcp;             /* If true, no TCP server is listening.  */
  78   bool disable_udp;             /* If true, no UDP server is listening.  */
  79 };
  80
  81 /* Instructions for setting up the libresolv redirection.  */
  82 struct resolv_redirect_config
  83 {
  84   /* The response_callback function is called for every incoming DNS
  85      packet, over UDP or TCP.  It must be specified, the other
  86      configuration settings are optional.  */
  87   void (*response_callback) (const struct resolv_response_context *,
  88                              struct resolv_response_builder *,
  89                              const char *qname,
  90                              uint16_t qclass, uint16_t qtype);
  91
  92   /* Per-server configuration.  */
  93   struct resolv_redirect_server_config servers[resolv_max_test_servers];
  94
  95   /* Search path entries.  The first entry serves as the default
  96      domain name as well.  */
  97   const char *search[7];
  98
  99   /* Number of servers to activate in resolv.  0 means the default,
 100      resolv_max_test_servers.  */
 101   int nscount;
 102
 103   /* If true, use a single thread to process all UDP queries.  This
 104      may results in more predictable ordering of queries and
 105      responses.  */
 106   bool single_thread_udp;
 107
 108   /* Do not rewrite the _res variable or change NSS defaults.  Use
 109      server_address_overrides below to tell the testing framework on
 110      which addresses to create the servers.  */
 111   bool disable_redirect;
 112
 113   /* Use these addresses for creating the DNS servers.  The array must
 114      have ns_count (or resolv_max_test_servers) sockaddr * elements if
 115      not NULL.  */
 116   const struct sockaddr *const *server_address_overrides;
 117 };
 118
 119 /* Configure NSS to use, nss_dns only for applicable databases, and try
 120    to put the process into a network namespace for better isolation.
 121    This may have to be called before resolv_test_start, before the
 122    process creates any threads.  Otherwise, initialization is
 123    performed by resolv_test_start implicitly.  */
 124 void resolv_test_init (void);
 125
 126 /* Initiate resolver testing.  This updates the _res variable as
 127    needed.  As a side effect, NSS is reconfigured to use nss_dns only
 128    for applicable databases, and the process may enter a network
 129    namespace for better isolation.  */
 130 struct resolv_test *resolv_test_start (struct resolv_redirect_config);
 131
 132 /* Call this function at the end of resolver testing, to free
 133    resources and report pending errors (if any).  */
 134 void resolv_test_end (struct resolv_test *);
 135
 136 /* The remaining facilities in this file are used for constructing
 137    response packets from the response_callback function.  */
 138
 139 /* Special settings for constructing responses from the callback.  */
 140 struct resolv_response_flags
 141 {
 142   /* 4-bit response code to incorporate into the response. */
 143   unsigned char rcode;
 144
 145   /* If true, the TC (truncation) flag will be set.  */
 146   bool tc;
 147
 148   /* If true, the AD (authenticated data) flag will be set.  */
 149   bool ad;
 150
 151   /* If true, do not set the RA (recursion available) flag in the
 152      response.  */
 153   bool clear_ra;
 154
 155   /* Initial section count values.  Can be used to artificially
 156      increase the counts, for malformed packet testing.*/
 157   unsigned short qdcount;
 158   unsigned short ancount;
 159   unsigned short nscount;
 160   unsigned short adcount;
 161 };
 162
 163 /* Begin a new response with the requested flags.  Must be called
 164    first.  */
 165 void resolv_response_init (struct resolv_response_builder *,
 166                            struct resolv_response_flags);
 167
 168 /* Switches to the section in the response packet.  Only forward
 169    movement is supported.  */
 170 void resolv_response_section (struct resolv_response_builder *, ns_sect);
 171
 172 /* Add a question record to the question section.  */
 173 void resolv_response_add_question (struct resolv_response_builder *,
 174                                    const char *name, uint16_t class,
 175                                    uint16_t type);
 176 /* Starts a new resource record with the specified owner name, class,
 177    type, and TTL.  Data is supplied with resolv_response_add_data or
 178    resolv_response_add_name.  */
 179 void resolv_response_open_record (struct resolv_response_builder *,
 180                                   const char *name, uint16_t class,
 181                                   uint16_t type, uint32_t ttl);
 182
 183 /* Add unstructed bytes to the RDATA part of a resource record.  */
 184 void resolv_response_add_data (struct resolv_response_builder *,
 185                                const void *, size_t);
 186
 187 /* Add a compressed domain name to the RDATA part of a resource
 188    record.  */
 189 void resolv_response_add_name (struct resolv_response_builder *,
 190                                const char *name);
 191
 192 /* Mark the end of the constructed record.  Must be called last.  */
 193 void resolv_response_close_record (struct resolv_response_builder *);
 194
 195 /* Drop this query packet (that is, do not send a response, not even
 196    an empty packet).  */
 197 void resolv_response_drop (struct resolv_response_builder *);
 198
 199 /* In TCP mode, close the connection after this packet (if a response
 200    is sent).  */
 201 void resolv_response_close (struct resolv_response_builder *);
 202
 203 /* The size of the response packet built so far.  */
 204 size_t resolv_response_length (const struct resolv_response_builder *);
 205
 206 /* Allocates a response builder tied to a specific query packet,
 207    starting at QUERY_BUFFER, containing QUERY_LENGTH bytes.  */
 208 struct resolv_response_builder *
 209   resolv_response_builder_allocate (const unsigned char *query_buffer,
 210                                     size_t query_length);
 211
 212 /* Deallocates a response buffer.  */
 213 void resolv_response_builder_free (struct resolv_response_builder *);
 214
 215 /* Sends a UDP response using a specific context.  This can be used to
 216    reorder or duplicate responses, along with
 217    resolv_response_context_duplicate and
 218    response_builder_allocate.  */
 219 void resolv_response_send_udp (const struct resolv_response_context *,
 220                                struct resolv_response_builder *);
 221
 222 __END_DECLS
 223
 224 #endif /* SUPPORT_RESOLV_TEST_H */