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 */