1/* DNS test framework and libresolv redirection.
2 Copyright (C) 2016-2020 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. */
29struct 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. */
40struct 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. */
51struct resolv_response_builder;
52
53/* This opaque struct collects information about the resolver testing
54 currently in progress. */
55struct resolv_test;
56
57enum
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. */
64struct 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. */
71struct 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. */
113void 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. */
119struct 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). */
123void 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. */
129struct 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 /* If true, the AD (authenticated data) flag will be set. */
138 bool ad;
139
140 /* Initial section count values. Can be used to artificially
141 increase the counts, for malformed packet testing.*/
142 unsigned short qdcount;
143 unsigned short ancount;
144 unsigned short nscount;
145 unsigned short adcount;
146};
147
148/* Begin a new response with the requested flags. Must be called
149 first. */
150void resolv_response_init (struct resolv_response_builder *,
151 struct resolv_response_flags);
152
153/* Switches to the section in the response packet. Only forward
154 movement is supported. */
155void resolv_response_section (struct resolv_response_builder *, ns_sect);
156
157/* Add a question record to the question section. */
158void resolv_response_add_question (struct resolv_response_builder *,
159 const char *name, uint16_t class,
160 uint16_t type);
161/* Starts a new resource record with the specified owner name, class,
162 type, and TTL. Data is supplied with resolv_response_add_data or
163 resolv_response_add_name. */
164void resolv_response_open_record (struct resolv_response_builder *,
165 const char *name, uint16_t class,
166 uint16_t type, uint32_t ttl);
167
168/* Add unstructed bytes to the RDATA part of a resource record. */
169void resolv_response_add_data (struct resolv_response_builder *,
170 const void *, size_t);
171
172/* Add a compressed domain name to the RDATA part of a resource
173 record. */
174void resolv_response_add_name (struct resolv_response_builder *,
175 const char *name);
176
177/* Mark the end of the constructed record. Must be called last. */
178void resolv_response_close_record (struct resolv_response_builder *);
179
180/* Drop this query packet (that is, do not send a response, not even
181 an empty packet). */
182void resolv_response_drop (struct resolv_response_builder *);
183
184/* In TCP mode, close the connection after this packet (if a response
185 is sent). */
186void resolv_response_close (struct resolv_response_builder *);
187
188/* The size of the response packet built so far. */
189size_t resolv_response_length (const struct resolv_response_builder *);
190
191__END_DECLS
192
193#endif /* SUPPORT_RESOLV_TEST_H */
194