support/resolv_test.h

   1 /* DNS test framework and libresolv redirection.
   2    Copyright (C) 2016-2017 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    <http://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
  98 /* Configure NSS to use, nss_dns only for aplicable databases, and try
  99    to put the process into a network namespace for better isolation.
 100    This may have to be called before resolv_test_start, before the
 101    process creates any threads.  Otherwise, initialization is
 102    performed by resolv_test_start implicitly.  */
 103 void resolv_test_init (void);
 104
 105 /* Initiate resolver testing.  This updates the _res variable as
 106    needed.  As a side effect, NSS is reconfigured to use nss_dns only
 107    for aplicable databases, and the process may enter a network
 108    namespace for better isolation.  */
 109 struct resolv_test *resolv_test_start (struct resolv_redirect_config);
 110
 111 /* Call this function at the end of resolver testing, to free
 112    resources and report pending errors (if any).  */
 113 void resolv_test_end (struct resolv_test *);
 114
 115 /* The remaining facilities in this file are used for constructing
 116    response packets from the response_callback function.  */
 117
 118 /* Special settings for constructing responses from the callback.  */
 119 struct resolv_response_flags
 120 {
 121   /* 4-bit response code to incorporate into the response. */
 122   unsigned char rcode;
 123
 124   /* If true, the TC (truncation) flag will be set.  */
 125   bool tc;
 126
 127   /* Initial section count values.  Can be used to artificially
 128      increase the counts, for malformed packet testing.*/
 129   unsigned short qdcount;
 130   unsigned short ancount;
 131   unsigned short nscount;
 132   unsigned short adcount;
 133 };
 134
 135 /* Begin a new response with the requested flags.  Must be called
 136    first.  */
 137 void resolv_response_init (struct resolv_response_builder *,
 138                            struct resolv_response_flags);
 139
 140 /* Switches to the section in the response packet.  Only forward
 141    movement is supported.  */
 142 void resolv_response_section (struct resolv_response_builder *, ns_sect);
 143
 144 /* Add a question record to the question section.  */
 145 void resolv_response_add_question (struct resolv_response_builder *,
 146                                    const char *name, uint16_t class,
 147                                    uint16_t type);
 148 /* Starts a new resource record with the specified owner name, class,
 149    type, and TTL.  Data is supplied with resolv_response_add_data or
 150    resolv_response_add_name.  */
 151 void resolv_response_open_record (struct resolv_response_builder *,
 152                                   const char *name, uint16_t class,
 153                                   uint16_t type, uint32_t ttl);
 154
 155 /* Add unstructed bytes to the RDATA part of a resource record.  */
 156 void resolv_response_add_data (struct resolv_response_builder *,
 157                                const void *, size_t);
 158
 159 /* Add a compressed domain name to the RDATA part of a resource
 160    record.  */
 161 void resolv_response_add_name (struct resolv_response_builder *,
 162                                const char *name);
 163
 164 /* Mark the end of the constructed record.  Must be called last.  */
 165 void resolv_response_close_record (struct resolv_response_builder *);
 166
 167 /* Drop this query packet (that is, do not send a response, not even
 168    an empty packet).  */
 169 void resolv_response_drop (struct resolv_response_builder *);
 170
 171 /* In TCP mode, close the connection after this packet (if a response
 172    is sent).  */
 173 void resolv_response_close (struct resolv_response_builder *);
 174
 175 /* The size of the response packet built so far.  */
 176 size_t resolv_response_length (const struct resolv_response_builder *);
 177
 178 __END_DECLS
 179
 180 #endif /* SUPPORT_RESOLV_TEST_H */