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