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