support/resolv_test.h

   1 /* DNS test framework and libresolv redirection.
   2    Copyright (C) 2016-2019 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 struct provides context information when the response callback
  39    specified in struct resolv_redirect_config is invoked. */
  40 struct resolv_response_context
  41 {
  42   const unsigned char *query_buffer;
  43   size_t query_length;
  44   int server_index;
  45   bool tcp;
  46   struct resolv_edns_info edns;
  47 };
  48
  49 /* This opaque struct is used to construct responses from within the
  50    response callback function.  */
  51 struct resolv_response_builder;
  52
  53 /* This opaque struct collects information about the resolver testing
  54    currently in progress.  */
  55 struct resolv_test;
  56
  57 enum
  58   {
  59     /* Maximum number of test servers supported by the framework.  */
  60     resolv_max_test_servers = 3,
  61   };
  62
  63 /* Configuration settings specific to individual test servers.  */
  64 struct resolv_redirect_server_config
  65 {
  66   bool disable_tcp;             /* If true, no TCP server is listening.  */
  67   bool disable_udp;             /* If true, no UDP server is listening.  */
  68 };
  69
  70 /* Instructions for setting up the libresolv redirection.  */
  71 struct resolv_redirect_config
  72 {
  73   /* The response_callback function is called for every incoming DNS
  74      packet, over UDP or TCP.  It must be specified, the other
  75      configuration settings are optional.  */
  76   void (*response_callback) (const struct resolv_response_context *,
  77                              struct resolv_response_builder *,
  78                              const char *qname,
  79                              uint16_t qclass, uint16_t qtype);
  80
  81   /* Per-server configuration.  */
  82   struct resolv_redirect_server_config servers[resolv_max_test_servers];
  83
  84   /* Search path entries.  The first entry serves as the default
  85      domain name as well.  */
  86   const char *search[7];
  87
  88   /* Number of servers to activate in resolv.  0 means the default,
  89      resolv_max_test_servers.  */
  90   int nscount;
  91
  92   /* If true, use a single thread to process all UDP queries.  This
  93      may results in more predictable ordering of queries and
  94      responses.  */
  95   bool single_thread_udp;
  96
  97   /* Do not rewrite the _res variable or change NSS defaults.  Use
  98      server_address_overrides below to tell the testing framework on
  99      which addresses to create the servers.  */
 100   bool disable_redirect;
 101
 102   /* Use these addresses for creating the DNS servers.  The array must
 103      have ns_count (or resolv_max_test_servers) sockaddr * elements if
 104      not NULL.  */
 105   const struct sockaddr *const *server_address_overrides;
 106 };
 107
 108 /* Configure NSS to use, nss_dns only for aplicable databases, and try
 109    to put the process into a network namespace for better isolation.
 110    This may have to be called before resolv_test_start, before the
 111    process creates any threads.  Otherwise, initialization is
 112    performed by resolv_test_start implicitly.  */
 113 void resolv_test_init (void);
 114
 115 /* Initiate resolver testing.  This updates the _res variable as
 116    needed.  As a side effect, NSS is reconfigured to use nss_dns only
 117    for aplicable databases, and the process may enter a network
 118    namespace for better isolation.  */
 119 struct resolv_test *resolv_test_start (struct resolv_redirect_config);
 120
 121 /* Call this function at the end of resolver testing, to free
 122    resources and report pending errors (if any).  */
 123 void resolv_test_end (struct resolv_test *);
 124
 125 /* The remaining facilities in this file are used for constructing
 126    response packets from the response_callback function.  */
 127
 128 /* Special settings for constructing responses from the callback.  */
 129 struct resolv_response_flags
 130 {
 131   /* 4-bit response code to incorporate into the response. */
 132   unsigned char rcode;
 133
 134   /* If true, the TC (truncation) flag will be set.  */
 135   bool tc;
 136
 137   /* Initial section count values.  Can be used to artificially
 138      increase the counts, for malformed packet testing.*/
 139   unsigned short qdcount;
 140   unsigned short ancount;
 141   unsigned short nscount;
 142   unsigned short adcount;
 143 };
 144
 145 /* Begin a new response with the requested flags.  Must be called
 146    first.  */
 147 void resolv_response_init (struct resolv_response_builder *,
 148                            struct resolv_response_flags);
 149
 150 /* Switches to the section in the response packet.  Only forward
 151    movement is supported.  */
 152 void resolv_response_section (struct resolv_response_builder *, ns_sect);
 153
 154 /* Add a question record to the question section.  */
 155 void resolv_response_add_question (struct resolv_response_builder *,
 156                                    const char *name, uint16_t class,
 157                                    uint16_t type);
 158 /* Starts a new resource record with the specified owner name, class,
 159    type, and TTL.  Data is supplied with resolv_response_add_data or
 160    resolv_response_add_name.  */
 161 void resolv_response_open_record (struct resolv_response_builder *,
 162                                   const char *name, uint16_t class,
 163                                   uint16_t type, uint32_t ttl);
 164
 165 /* Add unstructed bytes to the RDATA part of a resource record.  */
 166 void resolv_response_add_data (struct resolv_response_builder *,
 167                                const void *, size_t);
 168
 169 /* Add a compressed domain name to the RDATA part of a resource
 170    record.  */
 171 void resolv_response_add_name (struct resolv_response_builder *,
 172                                const char *name);
 173
 174 /* Mark the end of the constructed record.  Must be called last.  */
 175 void resolv_response_close_record (struct resolv_response_builder *);
 176
 177 /* Drop this query packet (that is, do not send a response, not even
 178    an empty packet).  */
 179 void resolv_response_drop (struct resolv_response_builder *);
 180
 181 /* In TCP mode, close the connection after this packet (if a response
 182    is sent).  */
 183 void resolv_response_close (struct resolv_response_builder *);
 184
 185 /* The size of the response packet built so far.  */
 186 size_t resolv_response_length (const struct resolv_response_builder *);
 187
 188 __END_DECLS
 189
 190 #endif /* SUPPORT_RESOLV_TEST_H */