xref: /freebsd/contrib/unbound/util/net_help.h (revision 5c1d97100348ef19878fa14671a9b70f3d963ed4)
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 struct config_strlist;
48 
49 /** DNS constants for uint16_t style flag manipulation. host byteorder.
50  *                                1  1  1  1  1  1
51  *  0  1  2  3  4  5  6  7  8  9  0  1  2  3  4  5
52  * +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
53  * |QR|   Opcode  |AA|TC|RD|RA| Z|AD|CD|   RCODE   |
54  * +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
55  */
56 /** CD flag */
57 #define BIT_CD 0x0010
58 /** AD flag */
59 #define BIT_AD 0x0020
60 /** Z flag */
61 #define BIT_Z  0x0040
62 /** RA flag */
63 #define BIT_RA 0x0080
64 /** RD flag */
65 #define BIT_RD 0x0100
66 /** TC flag */
67 #define BIT_TC 0x0200
68 /** AA flag */
69 #define BIT_AA 0x0400
70 /** QR flag */
71 #define BIT_QR 0x8000
72 /** get RCODE bits from uint16 flags */
73 #define FLAGS_GET_RCODE(f) ((f) & 0xf)
74 /** set RCODE bits in uint16 flags */
75 #define FLAGS_SET_RCODE(f, r) (f = (((f) & 0xfff0) | (r)))
76 
77 /** timeout in milliseconds for UDP queries to auth servers. */
78 #define UDP_AUTH_QUERY_TIMEOUT 3000
79 /** timeout in milliseconds for TCP queries to auth servers. */
80 #define TCP_AUTH_QUERY_TIMEOUT 3000
81 /** Advertised version of EDNS capabilities */
82 #define EDNS_ADVERTISED_VERSION         0
83 /** Advertised size of EDNS capabilities */
84 extern uint16_t EDNS_ADVERTISED_SIZE;
85 /** bits for EDNS bitfield */
86 #define EDNS_DO 0x8000 /* Dnssec Ok */
87 /** byte size of ip4 address */
88 #define INET_SIZE 4
89 /** byte size of ip6 address */
90 #define INET6_SIZE 16
91 
92 /** DNSKEY zone sign key flag */
93 #define DNSKEY_BIT_ZSK 0x0100
94 /** DNSKEY secure entry point, KSK flag */
95 #define DNSKEY_BIT_SEP 0x0001
96 
97 /** minimal responses when positive answer */
98 extern int MINIMAL_RESPONSES;
99 
100 /** rrset order roundrobin */
101 extern int RRSET_ROUNDROBIN;
102 
103 /** log tag queries with name instead of 'info' for filtering */
104 extern int LOG_TAG_QUERYREPLY;
105 
106 /**
107  * See if string is ip4 or ip6.
108  * @param str: IP specification.
109  * @return: true if string addr is an ip6 specced address.
110  */
111 int str_is_ip6(const char* str);
112 
113 /**
114  * Set fd nonblocking.
115  * @param s: file descriptor.
116  * @return: 0 on error (error is printed to log).
117  */
118 int fd_set_nonblock(int s);
119 
120 /**
121  * Set fd (back to) blocking.
122  * @param s: file descriptor.
123  * @return: 0 on error (error is printed to log).
124  */
125 int fd_set_block(int s);
126 
127 /**
128  * See if number is a power of 2.
129  * @param num: the value.
130  * @return: true if the number is a power of 2.
131  */
132 int is_pow2(size_t num);
133 
134 /**
135  * Allocate memory and copy over contents.
136  * @param data: what to copy over.
137  * @param len: length of data.
138  * @return: NULL on malloc failure, or newly malloced data.
139  */
140 void* memdup(void* data, size_t len);
141 
142 /**
143  * Prints the sockaddr in readable format with log_info. Debug helper.
144  * @param v: at what verbosity level to print this.
145  * @param str: descriptive string printed with it.
146  * @param addr: the sockaddr to print. Can be ip4 or ip6.
147  * @param addrlen: length of addr.
148  */
149 void log_addr(enum verbosity_value v, const char* str,
150 	struct sockaddr_storage* addr, socklen_t addrlen);
151 
152 /**
153  * Prints zone name and sockaddr in readable format with log_info. Debug.
154  * @param v: at what verbosity level to print this.
155  * @param str: descriptive string printed with it.
156  * @param zone: DNS domain name, uncompressed wireformat.
157  * @param addr: the sockaddr to print. Can be ip4 or ip6.
158  * @param addrlen: length of addr.
159  */
160 void log_name_addr(enum verbosity_value v, const char* str, uint8_t* zone,
161 	struct sockaddr_storage* addr, socklen_t addrlen);
162 
163 /**
164  * Log errno and addr.
165  * @param str: descriptive string printed with it.
166  * @param err: errno string to print, i.e. strerror(errno).
167  * @param addr: the sockaddr to print. Can be ip4 or ip6.
168  * @param addrlen: length of addr.
169  */
170 void log_err_addr(const char* str, const char* err,
171 	struct sockaddr_storage* addr, socklen_t addrlen);
172 
173 /**
174  * Convert address string, with "@port" appendix, to sockaddr.
175  * Uses DNS port by default.
176  * @param str: the string
177  * @param addr: where to store sockaddr.
178  * @param addrlen: length of stored sockaddr is returned.
179  * @return 0 on error.
180  */
181 int extstrtoaddr(const char* str, struct sockaddr_storage* addr,
182 	socklen_t* addrlen);
183 
184 /**
185  * Convert ip address string and port to sockaddr.
186  * @param ip: ip4 or ip6 address string.
187  * @param port: port number, host format.
188  * @param addr: where to store sockaddr.
189  * @param addrlen: length of stored sockaddr is returned.
190  * @return 0 on error.
191  */
192 int ipstrtoaddr(const char* ip, int port, struct sockaddr_storage* addr,
193 	socklen_t* addrlen);
194 
195 /**
196  * Convert ip netblock (ip/netsize) string and port to sockaddr.
197  * performs a copy internally to avoid writing over 'ip' string.
198  * @param ip: ip4 or ip6 address string.
199  * @param port: port number, host format.
200  * @param addr: where to store sockaddr.
201  * @param addrlen: length of stored sockaddr is returned.
202  * @param net: netblock size is returned.
203  * @return 0 on error.
204  */
205 int netblockstrtoaddr(const char* ip, int port, struct sockaddr_storage* addr,
206 	socklen_t* addrlen, int* net);
207 
208 /**
209  * Convert address string, with "@port" appendix, to sockaddr.
210  * It can also have an "#tls-auth-name" appendix (after the port).
211  * The returned tls-auth-name string is a pointer into the input string.
212  * Uses DNS port by default.
213  * @param str: the string
214  * @param addr: where to store sockaddr.
215  * @param addrlen: length of stored sockaddr is returned.
216  * @param auth_name: returned pointer to tls_auth_name, or NULL if none.
217  * @return 0 on error.
218  */
219 int authextstrtoaddr(char* str, struct sockaddr_storage* addr,
220 	socklen_t* addrlen, char** auth_name);
221 
222 /**
223  * Store port number into sockaddr structure
224  * @param addr: sockaddr structure, ip4 or ip6.
225  * @param addrlen: length of addr.
226  * @param port: port number to put into the addr.
227  */
228 void sockaddr_store_port(struct sockaddr_storage* addr, socklen_t addrlen,
229 	int port);
230 
231 /**
232  * Print string with neat domain name, type and class.
233  * @param v: at what verbosity level to print this.
234  * @param str: string of message.
235  * @param name: domain name uncompressed wireformat.
236  * @param type: host format RR type.
237  * @param dclass: host format RR class.
238  */
239 void log_nametypeclass(enum verbosity_value v, const char* str,
240 	uint8_t* name, uint16_t type, uint16_t dclass);
241 
242 /**
243  * Like log_nametypeclass, but logs with log_query for query logging
244  */
245 void log_query_in(const char* str, uint8_t* name, uint16_t type,
246 	uint16_t dclass);
247 
248 /**
249  * Compare two sockaddrs. Imposes an ordering on the addresses.
250  * Compares address and port.
251  * @param addr1: address 1.
252  * @param len1: lengths of addr1.
253  * @param addr2: address 2.
254  * @param len2: lengths of addr2.
255  * @return: 0 if addr1 == addr2. -1 if addr1 is smaller, +1 if larger.
256  */
257 int sockaddr_cmp(struct sockaddr_storage* addr1, socklen_t len1,
258 	struct sockaddr_storage* addr2, socklen_t len2);
259 
260 /**
261  * Compare two sockaddrs. Compares address, not the port.
262  * @param addr1: address 1.
263  * @param len1: lengths of addr1.
264  * @param addr2: address 2.
265  * @param len2: lengths of addr2.
266  * @return: 0 if addr1 == addr2. -1 if addr1 is smaller, +1 if larger.
267  */
268 int sockaddr_cmp_addr(struct sockaddr_storage* addr1, socklen_t len1,
269 	struct sockaddr_storage* addr2, socklen_t len2);
270 
271 /**
272  * Checkout address family.
273  * @param addr: the sockaddr to examine.
274  * @param len: the length of addr.
275  * @return: true if sockaddr is ip6.
276  */
277 int addr_is_ip6(struct sockaddr_storage* addr, socklen_t len);
278 
279 /**
280  * Make sure the sockaddr ends in zeroes. For tree insertion and subsequent
281  * comparison.
282  * @param addr: the ip4 or ip6 addr.
283  * @param len: length of addr.
284  * @param net: number of bits to leave untouched, the rest of the netblock
285  * 	address is zeroed.
286  */
287 void addr_mask(struct sockaddr_storage* addr, socklen_t len, int net);
288 
289 /**
290  * See how many bits are shared, equal, between two addrs.
291  * @param addr1: first addr.
292  * @param net1: netblock size of first addr.
293  * @param addr2: second addr.
294  * @param net2: netblock size of second addr.
295  * @param addrlen: length of first addr and of second addr.
296  * 	They must be of the same length (i.e. same type IP4, IP6).
297  * @return: number of bits the same.
298  */
299 int addr_in_common(struct sockaddr_storage* addr1, int net1,
300 	struct sockaddr_storage* addr2, int net2, socklen_t addrlen);
301 
302 /**
303  * Put address into string, works for IPv4 and IPv6.
304  * @param addr: address
305  * @param addrlen: length of address
306  * @param buf: result string stored here
307  * @param len: length of buf.
308  * On failure a string with "error" is stored inside.
309  */
310 void addr_to_str(struct sockaddr_storage* addr, socklen_t addrlen,
311 	char* buf, size_t len);
312 
313 /**
314  * See if sockaddr is an ipv6 mapped ipv4 address, "::ffff:0.0.0.0"
315  * @param addr: address
316  * @param addrlen: length of address
317  * @return true if so
318  */
319 int addr_is_ip4mapped(struct sockaddr_storage* addr, socklen_t addrlen);
320 
321 /**
322  * See if sockaddr is 255.255.255.255.
323  * @param addr: address
324  * @param addrlen: length of address
325  * @return true if so
326  */
327 int addr_is_broadcast(struct sockaddr_storage* addr, socklen_t addrlen);
328 
329 /**
330  * See if sockaddr is 0.0.0.0 or ::0.
331  * @param addr: address
332  * @param addrlen: length of address
333  * @return true if so
334  */
335 int addr_is_any(struct sockaddr_storage* addr, socklen_t addrlen);
336 
337 /**
338  * Insert new socket list item. If fails logs error.
339  * @param list: pointer to pointer to first item.
340  * @param addr: address or NULL if 'cache'.
341  * @param len: length of addr, or 0 if 'cache'.
342  * @param region: where to allocate
343  */
344 void sock_list_insert(struct sock_list** list, struct sockaddr_storage* addr,
345 	socklen_t len, struct regional* region);
346 
347 /**
348  * Append one list to another.  Must both be from same qstate(regional).
349  * @param list: pointer to result list that is modified.
350  * @param add: item(s) to add.  They are prepended to list.
351  */
352 void sock_list_prepend(struct sock_list** list, struct sock_list* add);
353 
354 /**
355  * Find addr in list.
356  * @param list: to search in
357  * @param addr: address to look for.
358  * @param len: length. Can be 0, look for 'cache entry'.
359  * @return true if found.
360  */
361 int sock_list_find(struct sock_list* list, struct sockaddr_storage* addr,
362         socklen_t len);
363 
364 /**
365  * Merge socklist into another socket list.  Allocates the new entries
366  * freshly and copies them over, so also performs a region switchover.
367  * Allocation failures are logged.
368  * @param list: the destination list (checked for duplicates)
369  * @param region: where to allocate
370  * @param add: the list of entries to add.
371  */
372 void sock_list_merge(struct sock_list** list, struct regional* region,
373 	struct sock_list* add);
374 
375 /**
376  * Log libcrypto error with descriptive string. Calls log_err().
377  * @param str: what failed.
378  */
379 void log_crypto_err(const char* str);
380 
381 /**
382  * Set SSL_OP_NOxxx options on SSL context to disable bad crypto
383  * @param ctxt: SSL_CTX*
384  * @return false on failure.
385  */
386 int listen_sslctx_setup(void* ctxt);
387 
388 /**
389  * Further setup of listening SSL context, after keys loaded.
390  * @param ctxt: SSL_CTX*
391  */
392 void listen_sslctx_setup_2(void* ctxt);
393 
394 /**
395  * create SSL listen context
396  * @param key: private key file.
397  * @param pem: public key cert.
398  * @param verifypem: if nonNULL, verifylocation file.
399  * return SSL_CTX* or NULL on failure (logged).
400  */
401 void* listen_sslctx_create(char* key, char* pem, char* verifypem);
402 
403 /**
404  * create SSL connect context
405  * @param key: if nonNULL (also pem nonNULL), the client private key.
406  * @param pem: client public key (or NULL if key is NULL).
407  * @param verifypem: if nonNULL used for verifylocation file.
408  * @param wincert: add system certificate store to ctx (add to verifypem ca
409  * 	certs).
410  * @return SSL_CTX* or NULL on failure (logged).
411  */
412 void* connect_sslctx_create(char* key, char* pem, char* verifypem, int wincert);
413 
414 /**
415  * accept a new fd and wrap it in a BIO in SSL
416  * @param sslctx: the SSL_CTX to use (from listen_sslctx_create()).
417  * @param fd: from accept, nonblocking.
418  * @return SSL or NULL on alloc failure.
419  */
420 void* incoming_ssl_fd(void* sslctx, int fd);
421 
422 /**
423  * connect a new fd and wrap it in a BIO in SSL
424  * @param sslctx: the SSL_CTX to use (from connect_sslctx_create())
425  * @param fd: from connect.
426  * @return SSL or NULL on alloc failure
427  */
428 void* outgoing_ssl_fd(void* sslctx, int fd);
429 
430 /**
431  * Initialize openssl locking for thread safety
432  * @return false on failure (alloc failure).
433  */
434 int ub_openssl_lock_init(void);
435 
436 /**
437  * De-init the allocated openssl locks
438  */
439 void ub_openssl_lock_delete(void);
440 
441 /**
442  * setup TLS session ticket
443  * @param sslctx: the SSL_CTX to use (from connect_sslctx_create())
444  * @param tls_session_ticket_keys: TLS ticket secret filenames
445  * @return false on failure (alloc failure).
446  */
447 int listen_sslctx_setup_ticket_keys(void* sslctx,
448 	struct config_strlist* tls_session_ticket_keys);
449 
450 /**
451  * callback TLS session ticket encrypt and decrypt
452  * For use with SSL_CTX_set_tlsext_ticket_key_cb
453  * @param s: the SSL_CTX to use (from connect_sslctx_create())
454  * @param key_name: secret name, 16 bytes
455  * @param iv: up to EVP_MAX_IV_LENGTH.
456  * @param evp_ctx: the evp cipher context, function sets this.
457  * @param hmac_ctx: the hmax context, function sets this.
458  * @param enc: 1 is encrypt, 0 is decrypt
459  * @return 0 on no ticket, 1 for okay, and 2 for okay but renew the ticket
460  * 	(the ticket is decrypt only). and <0 for failures.
461  */
462 int tls_session_ticket_key_cb(void *s, unsigned char* key_name,unsigned char* iv, void *evp_ctx, void *hmac_ctx, int enc);
463 
464 /** Free memory used for TLS session ticket keys */
465 void listen_sslctx_delete_ticket_keys(void);
466 
467 #endif /* NET_HELP_H */
468