net_help.h revision 269257
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"
45struct sock_list;
46struct 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 seconds for UDP queries to auth servers. */
77#define UDP_AUTH_QUERY_TIMEOUT 4
78/** timeout in seconds for TCP queries to auth servers. */
79#define TCP_AUTH_QUERY_TIMEOUT 30
80/** Advertised version of EDNS capabilities */
81#define EDNS_ADVERTISED_VERSION         0
82/** Advertised size of EDNS capabilities */
83extern 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 */
97extern int MINIMAL_RESPONSES;
98
99/** rrset order roundrobin */
100extern 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 */
107int 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 */
114int 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 */
121int 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 */
128int 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 */
136void* 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 */
145void 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 */
156void log_name_addr(enum verbosity_value v, const char* str, uint8_t* zone,
157	struct sockaddr_storage* addr, socklen_t addrlen);
158
159/**
160 * Convert address string, with "@port" appendix, to sockaddr.
161 * Uses DNS port by default.
162 * @param str: the string
163 * @param addr: where to store sockaddr.
164 * @param addrlen: length of stored sockaddr is returned.
165 * @return 0 on error.
166 */
167int extstrtoaddr(const char* str, struct sockaddr_storage* addr,
168	socklen_t* addrlen);
169
170/**
171 * Convert ip address string and port to sockaddr.
172 * @param ip: ip4 or ip6 address string.
173 * @param port: port number, host format.
174 * @param addr: where to store sockaddr.
175 * @param addrlen: length of stored sockaddr is returned.
176 * @return 0 on error.
177 */
178int ipstrtoaddr(const char* ip, int port, struct sockaddr_storage* addr,
179	socklen_t* addrlen);
180
181/**
182 * Convert ip netblock (ip/netsize) string and port to sockaddr.
183 * *SLOW*, does a malloc internally to avoid writing over 'ip' string.
184 * @param ip: ip4 or ip6 address string.
185 * @param port: port number, host format.
186 * @param addr: where to store sockaddr.
187 * @param addrlen: length of stored sockaddr is returned.
188 * @param net: netblock size is returned.
189 * @return 0 on error.
190 */
191int netblockstrtoaddr(const char* ip, int port, struct sockaddr_storage* addr,
192	socklen_t* addrlen, int* net);
193
194/**
195 * Print string with neat domain name, type and class.
196 * @param v: at what verbosity level to print this.
197 * @param str: string of message.
198 * @param name: domain name uncompressed wireformat.
199 * @param type: host format RR type.
200 * @param dclass: host format RR class.
201 */
202void log_nametypeclass(enum verbosity_value v, const char* str,
203	uint8_t* name, uint16_t type, uint16_t dclass);
204
205/**
206 * Compare two sockaddrs. Imposes an ordering on the addresses.
207 * Compares address and port.
208 * @param addr1: address 1.
209 * @param len1: lengths of addr1.
210 * @param addr2: address 2.
211 * @param len2: lengths of addr2.
212 * @return: 0 if addr1 == addr2. -1 if addr1 is smaller, +1 if larger.
213 */
214int sockaddr_cmp(struct sockaddr_storage* addr1, socklen_t len1,
215	struct sockaddr_storage* addr2, socklen_t len2);
216
217/**
218 * Compare two sockaddrs. Compares address, not the port.
219 * @param addr1: address 1.
220 * @param len1: lengths of addr1.
221 * @param addr2: address 2.
222 * @param len2: lengths of addr2.
223 * @return: 0 if addr1 == addr2. -1 if addr1 is smaller, +1 if larger.
224 */
225int sockaddr_cmp_addr(struct sockaddr_storage* addr1, socklen_t len1,
226	struct sockaddr_storage* addr2, socklen_t len2);
227
228/**
229 * Checkout address family.
230 * @param addr: the sockaddr to examine.
231 * @param len: the length of addr.
232 * @return: true if sockaddr is ip6.
233 */
234int addr_is_ip6(struct sockaddr_storage* addr, socklen_t len);
235
236/**
237 * Make sure the sockaddr ends in zeroes. For tree insertion and subsequent
238 * comparison.
239 * @param addr: the ip4 or ip6 addr.
240 * @param len: length of addr.
241 * @param net: number of bits to leave untouched, the rest of the netblock
242 * 	address is zeroed.
243 */
244void addr_mask(struct sockaddr_storage* addr, socklen_t len, int net);
245
246/**
247 * See how many bits are shared, equal, between two addrs.
248 * @param addr1: first addr.
249 * @param net1: netblock size of first addr.
250 * @param addr2: second addr.
251 * @param net2: netblock size of second addr.
252 * @param addrlen: length of first addr and of second addr.
253 * 	They must be of the same length (i.e. same type IP4, IP6).
254 * @return: number of bits the same.
255 */
256int addr_in_common(struct sockaddr_storage* addr1, int net1,
257	struct sockaddr_storage* addr2, int net2, socklen_t addrlen);
258
259/**
260 * Put address into string, works for IPv4 and IPv6.
261 * @param addr: address
262 * @param addrlen: length of address
263 * @param buf: result string stored here
264 * @param len: length of buf.
265 * On failure a string with "error" is stored inside.
266 */
267void addr_to_str(struct sockaddr_storage* addr, socklen_t addrlen,
268	char* buf, size_t len);
269
270/**
271 * See if sockaddr is an ipv6 mapped ipv4 address, "::ffff:0.0.0.0"
272 * @param addr: address
273 * @param addrlen: length of address
274 * @return true if so
275 */
276int addr_is_ip4mapped(struct sockaddr_storage* addr, socklen_t addrlen);
277
278/**
279 * See if sockaddr is 255.255.255.255.
280 * @param addr: address
281 * @param addrlen: length of address
282 * @return true if so
283 */
284int addr_is_broadcast(struct sockaddr_storage* addr, socklen_t addrlen);
285
286/**
287 * See if sockaddr is 0.0.0.0 or ::0.
288 * @param addr: address
289 * @param addrlen: length of address
290 * @return true if so
291 */
292int addr_is_any(struct sockaddr_storage* addr, socklen_t addrlen);
293
294/**
295 * Insert new socket list item. If fails logs error.
296 * @param list: pointer to pointer to first item.
297 * @param addr: address or NULL if 'cache'.
298 * @param len: length of addr, or 0 if 'cache'.
299 * @param region: where to allocate
300 */
301void sock_list_insert(struct sock_list** list, struct sockaddr_storage* addr,
302	socklen_t len, struct regional* region);
303
304/**
305 * Append one list to another.  Must both be from same qstate(regional).
306 * @param list: pointer to result list that is modified.
307 * @param add: item(s) to add.  They are prepended to list.
308 */
309void sock_list_prepend(struct sock_list** list, struct sock_list* add);
310
311/**
312 * Find addr in list.
313 * @param list: to search in
314 * @param addr: address to look for.
315 * @param len: length. Can be 0, look for 'cache entry'.
316 * @return true if found.
317 */
318int sock_list_find(struct sock_list* list, struct sockaddr_storage* addr,
319        socklen_t len);
320
321/**
322 * Merge socklist into another socket list.  Allocates the new entries
323 * freshly and copies them over, so also performs a region switchover.
324 * Allocation failures are logged.
325 * @param list: the destination list (checked for duplicates)
326 * @param region: where to allocate
327 * @param add: the list of entries to add.
328 */
329void sock_list_merge(struct sock_list** list, struct regional* region,
330	struct sock_list* add);
331
332/**
333 * Log libcrypto error with descriptive string. Calls log_err().
334 * @param str: what failed.
335 */
336void log_crypto_err(const char* str);
337
338/**
339 * create SSL listen context
340 * @param key: private key file.
341 * @param pem: public key cert.
342 * @param verifypem: if nonNULL, verifylocation file.
343 * return SSL_CTX* or NULL on failure (logged).
344 */
345void* listen_sslctx_create(char* key, char* pem, char* verifypem);
346
347/**
348 * create SSL connect context
349 * @param key: if nonNULL (also pem nonNULL), the client private key.
350 * @param pem: client public key (or NULL if key is NULL).
351 * @param verifypem: if nonNULL used for verifylocation file.
352 * @return SSL_CTX* or NULL on failure (logged).
353 */
354void* connect_sslctx_create(char* key, char* pem, char* verifypem);
355
356/**
357 * accept a new fd and wrap it in a BIO in SSL
358 * @param sslctx: the SSL_CTX to use (from listen_sslctx_create()).
359 * @param fd: from accept, nonblocking.
360 * @return SSL or NULL on alloc failure.
361 */
362void* incoming_ssl_fd(void* sslctx, int fd);
363
364/**
365 * connect a new fd and wrap it in a BIO in SSL
366 * @param sslctx: the SSL_CTX to use (from connect_sslctx_create())
367 * @param fd: from connect.
368 * @return SSL or NULL on alloc failure
369 */
370void* outgoing_ssl_fd(void* sslctx, int fd);
371
372/**
373 * Initialize openssl locking for thread safety
374 * @return false on failure (alloc failure).
375 */
376int ub_openssl_lock_init(void);
377
378/**
379 * De-init the allocated openssl locks
380 */
381void ub_openssl_lock_delete(void);
382
383#endif /* NET_HELP_H */
384