xref: /freebsd/contrib/unbound/util/net_help.h (revision a25896ca1270e25b657ceaa8d47d5699515f5c25)
1 /*
2  * util/net_help.h - network help functions
3  *
4  * Copyright (c) 2007, NLnet Labs. All rights reserved.
5  *
6  * This software is open source.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * Redistributions of source code must retain the above copyright notice,
13  * this list of conditions and the following disclaimer.
14  *
15  * Redistributions in binary form must reproduce the above copyright notice,
16  * this list of conditions and the following disclaimer in the documentation
17  * and/or other materials provided with the distribution.
18  *
19  * Neither the name of the NLNET LABS nor the names of its contributors may
20  * be used to endorse or promote products derived from this software without
21  * specific prior written permission.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
26  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
27  * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
28  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
29  * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
30  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
31  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
32  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
33  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34  */
35 
36 /**
37  * \file
38  *
39  * This file contains functions to perform network related tasks.
40  */
41 
42 #ifndef NET_HELP_H
43 #define NET_HELP_H
44 #include "util/log.h"
45 struct sock_list;
46 struct regional;
47 
48 /** DNS constants for uint16_t style flag manipulation. host byteorder.
49  *                                1  1  1  1  1  1
50  *  0  1  2  3  4  5  6  7  8  9  0  1  2  3  4  5
51  * +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
52  * |QR|   Opcode  |AA|TC|RD|RA| Z|AD|CD|   RCODE   |
53  * +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
54  */
55 /** CD flag */
56 #define BIT_CD 0x0010
57 /** AD flag */
58 #define BIT_AD 0x0020
59 /** Z flag */
60 #define BIT_Z  0x0040
61 /** RA flag */
62 #define BIT_RA 0x0080
63 /** RD flag */
64 #define BIT_RD 0x0100
65 /** TC flag */
66 #define BIT_TC 0x0200
67 /** AA flag */
68 #define BIT_AA 0x0400
69 /** QR flag */
70 #define BIT_QR 0x8000
71 /** get RCODE bits from uint16 flags */
72 #define FLAGS_GET_RCODE(f) ((f) & 0xf)
73 /** set RCODE bits in uint16 flags */
74 #define FLAGS_SET_RCODE(f, r) (f = (((f) & 0xfff0) | (r)))
75 
76 /** timeout in milliseconds for UDP queries to auth servers. */
77 #define UDP_AUTH_QUERY_TIMEOUT 3000
78 /** timeout in milliseconds for TCP queries to auth servers. */
79 #define TCP_AUTH_QUERY_TIMEOUT 3000
80 /** Advertised version of EDNS capabilities */
81 #define EDNS_ADVERTISED_VERSION         0
82 /** Advertised size of EDNS capabilities */
83 extern uint16_t EDNS_ADVERTISED_SIZE;
84 /** bits for EDNS bitfield */
85 #define EDNS_DO 0x8000 /* Dnssec Ok */
86 /** byte size of ip4 address */
87 #define INET_SIZE 4
88 /** byte size of ip6 address */
89 #define INET6_SIZE 16
90 
91 /** DNSKEY zone sign key flag */
92 #define DNSKEY_BIT_ZSK 0x0100
93 /** DNSKEY secure entry point, KSK flag */
94 #define DNSKEY_BIT_SEP 0x0001
95 
96 /** minimal responses when positive answer */
97 extern int MINIMAL_RESPONSES;
98 
99 /** rrset order roundrobin */
100 extern int RRSET_ROUNDROBIN;
101 
102 /**
103  * See if string is ip4 or ip6.
104  * @param str: IP specification.
105  * @return: true if string addr is an ip6 specced address.
106  */
107 int str_is_ip6(const char* str);
108 
109 /**
110  * Set fd nonblocking.
111  * @param s: file descriptor.
112  * @return: 0 on error (error is printed to log).
113  */
114 int fd_set_nonblock(int s);
115 
116 /**
117  * Set fd (back to) blocking.
118  * @param s: file descriptor.
119  * @return: 0 on error (error is printed to log).
120  */
121 int fd_set_block(int s);
122 
123 /**
124  * See if number is a power of 2.
125  * @param num: the value.
126  * @return: true if the number is a power of 2.
127  */
128 int is_pow2(size_t num);
129 
130 /**
131  * Allocate memory and copy over contents.
132  * @param data: what to copy over.
133  * @param len: length of data.
134  * @return: NULL on malloc failure, or newly malloced data.
135  */
136 void* memdup(void* data, size_t len);
137 
138 /**
139  * Prints the sockaddr in readable format with log_info. Debug helper.
140  * @param v: at what verbosity level to print this.
141  * @param str: descriptive string printed with it.
142  * @param addr: the sockaddr to print. Can be ip4 or ip6.
143  * @param addrlen: length of addr.
144  */
145 void log_addr(enum verbosity_value v, const char* str,
146 	struct sockaddr_storage* addr, socklen_t addrlen);
147 
148 /**
149  * Prints zone name and sockaddr in readable format with log_info. Debug.
150  * @param v: at what verbosity level to print this.
151  * @param str: descriptive string printed with it.
152  * @param zone: DNS domain name, uncompressed wireformat.
153  * @param addr: the sockaddr to print. Can be ip4 or ip6.
154  * @param addrlen: length of addr.
155  */
156 void log_name_addr(enum verbosity_value v, const char* str, uint8_t* zone,
157 	struct sockaddr_storage* addr, socklen_t addrlen);
158 
159 /**
160  * Log errno and addr.
161  * @param str: descriptive string printed with it.
162  * @param err: errno string to print, i.e. strerror(errno).
163  * @param addr: the sockaddr to print. Can be ip4 or ip6.
164  * @param addrlen: length of addr.
165  */
166 void log_err_addr(const char* str, const char* err,
167 	struct sockaddr_storage* addr, socklen_t addrlen);
168 
169 /**
170  * Convert address string, with "@port" appendix, to sockaddr.
171  * Uses DNS port by default.
172  * @param str: the string
173  * @param addr: where to store sockaddr.
174  * @param addrlen: length of stored sockaddr is returned.
175  * @return 0 on error.
176  */
177 int extstrtoaddr(const char* str, struct sockaddr_storage* addr,
178 	socklen_t* addrlen);
179 
180 /**
181  * Convert ip address string and port to sockaddr.
182  * @param ip: ip4 or ip6 address string.
183  * @param port: port number, host format.
184  * @param addr: where to store sockaddr.
185  * @param addrlen: length of stored sockaddr is returned.
186  * @return 0 on error.
187  */
188 int ipstrtoaddr(const char* ip, int port, struct sockaddr_storage* addr,
189 	socklen_t* addrlen);
190 
191 /**
192  * Convert ip netblock (ip/netsize) string and port to sockaddr.
193  * performs a copy internally to avoid writing over 'ip' string.
194  * @param ip: ip4 or ip6 address string.
195  * @param port: port number, host format.
196  * @param addr: where to store sockaddr.
197  * @param addrlen: length of stored sockaddr is returned.
198  * @param net: netblock size is returned.
199  * @return 0 on error.
200  */
201 int netblockstrtoaddr(const char* ip, int port, struct sockaddr_storage* addr,
202 	socklen_t* addrlen, int* net);
203 
204 /**
205  * Convert address string, with "@port" appendix, to sockaddr.
206  * It can also have an "#tls-auth-name" appendix (after the port).
207  * The returned tls-auth-name string is a pointer into the input string.
208  * Uses DNS port by default.
209  * @param str: the string
210  * @param addr: where to store sockaddr.
211  * @param addrlen: length of stored sockaddr is returned.
212  * @param auth_name: returned pointer to tls_auth_name, or NULL if none.
213  * @return 0 on error.
214  */
215 int authextstrtoaddr(char* str, struct sockaddr_storage* addr,
216 	socklen_t* addrlen, char** auth_name);
217 
218 /**
219  * Store port number into sockaddr structure
220  * @param addr: sockaddr structure, ip4 or ip6.
221  * @param addrlen: length of addr.
222  * @param port: port number to put into the addr.
223  */
224 void sockaddr_store_port(struct sockaddr_storage* addr, socklen_t addrlen,
225 	int port);
226 
227 /**
228  * Print string with neat domain name, type and class.
229  * @param v: at what verbosity level to print this.
230  * @param str: string of message.
231  * @param name: domain name uncompressed wireformat.
232  * @param type: host format RR type.
233  * @param dclass: host format RR class.
234  */
235 void log_nametypeclass(enum verbosity_value v, const char* str,
236 	uint8_t* name, uint16_t type, uint16_t dclass);
237 
238 /**
239  * Compare two sockaddrs. Imposes an ordering on the addresses.
240  * Compares address and port.
241  * @param addr1: address 1.
242  * @param len1: lengths of addr1.
243  * @param addr2: address 2.
244  * @param len2: lengths of addr2.
245  * @return: 0 if addr1 == addr2. -1 if addr1 is smaller, +1 if larger.
246  */
247 int sockaddr_cmp(struct sockaddr_storage* addr1, socklen_t len1,
248 	struct sockaddr_storage* addr2, socklen_t len2);
249 
250 /**
251  * Compare two sockaddrs. Compares address, not the port.
252  * @param addr1: address 1.
253  * @param len1: lengths of addr1.
254  * @param addr2: address 2.
255  * @param len2: lengths of addr2.
256  * @return: 0 if addr1 == addr2. -1 if addr1 is smaller, +1 if larger.
257  */
258 int sockaddr_cmp_addr(struct sockaddr_storage* addr1, socklen_t len1,
259 	struct sockaddr_storage* addr2, socklen_t len2);
260 
261 /**
262  * Checkout address family.
263  * @param addr: the sockaddr to examine.
264  * @param len: the length of addr.
265  * @return: true if sockaddr is ip6.
266  */
267 int addr_is_ip6(struct sockaddr_storage* addr, socklen_t len);
268 
269 /**
270  * Make sure the sockaddr ends in zeroes. For tree insertion and subsequent
271  * comparison.
272  * @param addr: the ip4 or ip6 addr.
273  * @param len: length of addr.
274  * @param net: number of bits to leave untouched, the rest of the netblock
275  * 	address is zeroed.
276  */
277 void addr_mask(struct sockaddr_storage* addr, socklen_t len, int net);
278 
279 /**
280  * See how many bits are shared, equal, between two addrs.
281  * @param addr1: first addr.
282  * @param net1: netblock size of first addr.
283  * @param addr2: second addr.
284  * @param net2: netblock size of second addr.
285  * @param addrlen: length of first addr and of second addr.
286  * 	They must be of the same length (i.e. same type IP4, IP6).
287  * @return: number of bits the same.
288  */
289 int addr_in_common(struct sockaddr_storage* addr1, int net1,
290 	struct sockaddr_storage* addr2, int net2, socklen_t addrlen);
291 
292 /**
293  * Put address into string, works for IPv4 and IPv6.
294  * @param addr: address
295  * @param addrlen: length of address
296  * @param buf: result string stored here
297  * @param len: length of buf.
298  * On failure a string with "error" is stored inside.
299  */
300 void addr_to_str(struct sockaddr_storage* addr, socklen_t addrlen,
301 	char* buf, size_t len);
302 
303 /**
304  * See if sockaddr is an ipv6 mapped ipv4 address, "::ffff:0.0.0.0"
305  * @param addr: address
306  * @param addrlen: length of address
307  * @return true if so
308  */
309 int addr_is_ip4mapped(struct sockaddr_storage* addr, socklen_t addrlen);
310 
311 /**
312  * See if sockaddr is 255.255.255.255.
313  * @param addr: address
314  * @param addrlen: length of address
315  * @return true if so
316  */
317 int addr_is_broadcast(struct sockaddr_storage* addr, socklen_t addrlen);
318 
319 /**
320  * See if sockaddr is 0.0.0.0 or ::0.
321  * @param addr: address
322  * @param addrlen: length of address
323  * @return true if so
324  */
325 int addr_is_any(struct sockaddr_storage* addr, socklen_t addrlen);
326 
327 /**
328  * Insert new socket list item. If fails logs error.
329  * @param list: pointer to pointer to first item.
330  * @param addr: address or NULL if 'cache'.
331  * @param len: length of addr, or 0 if 'cache'.
332  * @param region: where to allocate
333  */
334 void sock_list_insert(struct sock_list** list, struct sockaddr_storage* addr,
335 	socklen_t len, struct regional* region);
336 
337 /**
338  * Append one list to another.  Must both be from same qstate(regional).
339  * @param list: pointer to result list that is modified.
340  * @param add: item(s) to add.  They are prepended to list.
341  */
342 void sock_list_prepend(struct sock_list** list, struct sock_list* add);
343 
344 /**
345  * Find addr in list.
346  * @param list: to search in
347  * @param addr: address to look for.
348  * @param len: length. Can be 0, look for 'cache entry'.
349  * @return true if found.
350  */
351 int sock_list_find(struct sock_list* list, struct sockaddr_storage* addr,
352         socklen_t len);
353 
354 /**
355  * Merge socklist into another socket list.  Allocates the new entries
356  * freshly and copies them over, so also performs a region switchover.
357  * Allocation failures are logged.
358  * @param list: the destination list (checked for duplicates)
359  * @param region: where to allocate
360  * @param add: the list of entries to add.
361  */
362 void sock_list_merge(struct sock_list** list, struct regional* region,
363 	struct sock_list* add);
364 
365 /**
366  * Log libcrypto error with descriptive string. Calls log_err().
367  * @param str: what failed.
368  */
369 void log_crypto_err(const char* str);
370 
371 /**
372  * Set SSL_OP_NOxxx options on SSL context to disable bad crypto
373  * @param ctxt: SSL_CTX*
374  * @return false on failure.
375  */
376 int listen_sslctx_setup(void* ctxt);
377 
378 /**
379  * Further setup of listening SSL context, after keys loaded.
380  * @param ctxt: SSL_CTX*
381  */
382 void listen_sslctx_setup_2(void* ctxt);
383 
384 /**
385  * create SSL listen context
386  * @param key: private key file.
387  * @param pem: public key cert.
388  * @param verifypem: if nonNULL, verifylocation file.
389  * return SSL_CTX* or NULL on failure (logged).
390  */
391 void* listen_sslctx_create(char* key, char* pem, char* verifypem);
392 
393 /**
394  * create SSL connect context
395  * @param key: if nonNULL (also pem nonNULL), the client private key.
396  * @param pem: client public key (or NULL if key is NULL).
397  * @param verifypem: if nonNULL used for verifylocation file.
398  * @param wincert: add system certificate store to ctx (add to verifypem ca
399  * 	certs).
400  * @return SSL_CTX* or NULL on failure (logged).
401  */
402 void* connect_sslctx_create(char* key, char* pem, char* verifypem, int wincert);
403 
404 /**
405  * accept a new fd and wrap it in a BIO in SSL
406  * @param sslctx: the SSL_CTX to use (from listen_sslctx_create()).
407  * @param fd: from accept, nonblocking.
408  * @return SSL or NULL on alloc failure.
409  */
410 void* incoming_ssl_fd(void* sslctx, int fd);
411 
412 /**
413  * connect a new fd and wrap it in a BIO in SSL
414  * @param sslctx: the SSL_CTX to use (from connect_sslctx_create())
415  * @param fd: from connect.
416  * @return SSL or NULL on alloc failure
417  */
418 void* outgoing_ssl_fd(void* sslctx, int fd);
419 
420 /**
421  * Initialize openssl locking for thread safety
422  * @return false on failure (alloc failure).
423  */
424 int ub_openssl_lock_init(void);
425 
426 /**
427  * De-init the allocated openssl locks
428  */
429 void ub_openssl_lock_delete(void);
430 
431 #endif /* NET_HELP_H */
432