2 * util/net_help.h - network help functions
4 * Copyright (c) 2007, NLnet Labs. All rights reserved.
6 * This software is open source.
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
12 * Redistributions of source code must retain the above copyright notice,
13 * this list of conditions and the following disclaimer.
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.
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.
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.
39 * This file contains functions to perform network related tasks.
47 struct config_strlist;
49 /** DNS constants for uint16_t style flag manipulation. host byteorder.
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 * +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
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)))
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 */
89 /** byte size of ip6 address */
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
97 /** minimal responses when positive answer */
98 extern int MINIMAL_RESPONSES;
100 /** rrset order roundrobin */
101 extern int RRSET_ROUNDROBIN;
103 /** log tag queries with name instead of 'info' for filtering */
104 extern int LOG_TAG_QUERYREPLY;
107 * See if string is ip4 or ip6.
108 * @param str: IP specification.
109 * @return: true if string addr is an ip6 specced address.
111 int str_is_ip6(const char* str);
114 * Set fd nonblocking.
115 * @param s: file descriptor.
116 * @return: 0 on error (error is printed to log).
118 int fd_set_nonblock(int s);
121 * Set fd (back to) blocking.
122 * @param s: file descriptor.
123 * @return: 0 on error (error is printed to log).
125 int fd_set_block(int s);
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.
132 int is_pow2(size_t num);
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.
140 void* memdup(void* data, size_t len);
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.
149 void log_addr(enum verbosity_value v, const char* str,
150 struct sockaddr_storage* addr, socklen_t addrlen);
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.
160 void log_name_addr(enum verbosity_value v, const char* str, uint8_t* zone,
161 struct sockaddr_storage* addr, socklen_t addrlen);
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.
170 void log_err_addr(const char* str, const char* err,
171 struct sockaddr_storage* addr, socklen_t addrlen);
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.
181 int extstrtoaddr(const char* str, struct sockaddr_storage* addr,
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.
192 int ipstrtoaddr(const char* ip, int port, struct sockaddr_storage* addr,
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.
205 int netblockstrtoaddr(const char* ip, int port, struct sockaddr_storage* addr,
206 socklen_t* addrlen, int* net);
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.
219 int authextstrtoaddr(char* str, struct sockaddr_storage* addr,
220 socklen_t* addrlen, char** auth_name);
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.
228 void sockaddr_store_port(struct sockaddr_storage* addr, socklen_t addrlen,
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.
239 void log_nametypeclass(enum verbosity_value v, const char* str,
240 uint8_t* name, uint16_t type, uint16_t dclass);
243 * Like log_nametypeclass, but logs with log_query for query logging
245 void log_query_in(const char* str, uint8_t* name, uint16_t type,
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.
257 int sockaddr_cmp(struct sockaddr_storage* addr1, socklen_t len1,
258 struct sockaddr_storage* addr2, socklen_t len2);
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.
268 int sockaddr_cmp_addr(struct sockaddr_storage* addr1, socklen_t len1,
269 struct sockaddr_storage* addr2, socklen_t len2);
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.
277 int addr_is_ip6(struct sockaddr_storage* addr, socklen_t len);
280 * Make sure the sockaddr ends in zeroes. For tree insertion and subsequent
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
287 void addr_mask(struct sockaddr_storage* addr, socklen_t len, int net);
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.
299 int addr_in_common(struct sockaddr_storage* addr1, int net1,
300 struct sockaddr_storage* addr2, int net2, socklen_t addrlen);
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.
310 void addr_to_str(struct sockaddr_storage* addr, socklen_t addrlen,
311 char* buf, size_t len);
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
319 int addr_is_ip4mapped(struct sockaddr_storage* addr, socklen_t addrlen);
322 * See if sockaddr is 255.255.255.255.
323 * @param addr: address
324 * @param addrlen: length of address
327 int addr_is_broadcast(struct sockaddr_storage* addr, socklen_t addrlen);
330 * See if sockaddr is 0.0.0.0 or ::0.
331 * @param addr: address
332 * @param addrlen: length of address
335 int addr_is_any(struct sockaddr_storage* addr, socklen_t addrlen);
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
344 void sock_list_insert(struct sock_list** list, struct sockaddr_storage* addr,
345 socklen_t len, struct regional* region);
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.
352 void sock_list_prepend(struct sock_list** list, struct sock_list* add);
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.
361 int sock_list_find(struct sock_list* list, struct sockaddr_storage* addr,
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.
372 void sock_list_merge(struct sock_list** list, struct regional* region,
373 struct sock_list* add);
376 * Log libcrypto error with descriptive string. Calls log_err().
377 * @param str: what failed.
379 void log_crypto_err(const char* str);
382 * Log libcrypto error from errcode with descriptive string, calls log_err.
383 * @param str: what failed.
384 * @param err: error code from ERR_get_error.
386 void log_crypto_err_code(const char* str, unsigned long err);
389 * Log certificate details verbosity, string, of X509 cert
390 * @param level: verbosity level
391 * @param str: string to prefix on output
392 * @param cert: X509* structure.
394 void log_cert(unsigned level, const char* str, void* cert);
397 * Set SSL_OP_NOxxx options on SSL context to disable bad crypto
398 * @param ctxt: SSL_CTX*
399 * @return false on failure.
401 int listen_sslctx_setup(void* ctxt);
404 * Further setup of listening SSL context, after keys loaded.
405 * @param ctxt: SSL_CTX*
407 void listen_sslctx_setup_2(void* ctxt);
410 * create SSL listen context
411 * @param key: private key file.
412 * @param pem: public key cert.
413 * @param verifypem: if nonNULL, verifylocation file.
414 * return SSL_CTX* or NULL on failure (logged).
416 void* listen_sslctx_create(char* key, char* pem, char* verifypem);
419 * create SSL connect context
420 * @param key: if nonNULL (also pem nonNULL), the client private key.
421 * @param pem: client public key (or NULL if key is NULL).
422 * @param verifypem: if nonNULL used for verifylocation file.
423 * @param wincert: add system certificate store to ctx (add to verifypem ca
425 * @return SSL_CTX* or NULL on failure (logged).
427 void* connect_sslctx_create(char* key, char* pem, char* verifypem, int wincert);
430 * accept a new fd and wrap it in a BIO in SSL
431 * @param sslctx: the SSL_CTX to use (from listen_sslctx_create()).
432 * @param fd: from accept, nonblocking.
433 * @return SSL or NULL on alloc failure.
435 void* incoming_ssl_fd(void* sslctx, int fd);
438 * connect a new fd and wrap it in a BIO in SSL
439 * @param sslctx: the SSL_CTX to use (from connect_sslctx_create())
440 * @param fd: from connect.
441 * @return SSL or NULL on alloc failure
443 void* outgoing_ssl_fd(void* sslctx, int fd);
446 * check if authname SSL functionality is available, false if not
447 * @param auth_name: the name for the remote server, used for error print.
448 * @return false if SSL functionality to check the SSL name is not available.
450 int check_auth_name_for_ssl(char* auth_name);
453 * set auth name on SSL for verification
454 * @param ssl: SSL* to set
455 * @param auth_name: if NULL nothing happens, otherwise the name to check.
456 * @param use_sni: if SNI will be used.
457 * @return 1 on success or NULL auth_name, 0 on failure.
459 int set_auth_name_on_ssl(void* ssl, char* auth_name, int use_sni);
462 * Initialize openssl locking for thread safety
463 * @return false on failure (alloc failure).
465 int ub_openssl_lock_init(void);
468 * De-init the allocated openssl locks
470 void ub_openssl_lock_delete(void);
473 * setup TLS session ticket
474 * @param sslctx: the SSL_CTX to use (from connect_sslctx_create())
475 * @param tls_session_ticket_keys: TLS ticket secret filenames
476 * @return false on failure (alloc failure).
478 int listen_sslctx_setup_ticket_keys(void* sslctx,
479 struct config_strlist* tls_session_ticket_keys);
481 /** Free memory used for TLS session ticket keys */
482 void listen_sslctx_delete_ticket_keys(void);
485 * RPZ format netblock to network byte order address and netblock
486 * example RPZ netblock format dnames:
487 * - 24.10.100.51.198.rpz-ip -> 198.51.100.10/24
488 * - 32.10.zz.db8.2001.rpz-ip -> 2001:db8:0:0:0:0:0:10/32
489 * @param dname: the dname containing RPZ format netblock
490 * @param dnamelen: length of dname
491 * @param addr: where to store sockaddr.
492 * @param addrlen: length of stored sockaddr is returned.
493 * @param net: where to store netmask
494 * @param af: where to store address family.
495 * @return 0 on error.
497 int netblockdnametoaddr(uint8_t* dname, size_t dnamelen,
498 struct sockaddr_storage* addr, socklen_t* addrlen, int* net, int* af);
499 #endif /* NET_HELP_H */