1 /* DNS test framework and libresolv redirection. 2 Copyright (C) 2016-2022 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 aplicable 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 aplicable 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 */ 225