adb.h 19.8 KB
Newer Older
Michael Graff's avatar
Michael Graff committed
1
/*
Mark Andrews's avatar
Mark Andrews committed
2
 * Copyright (C) 2004-2008, 2011, 2013, 2014  Internet Systems Consortium, Inc. ("ISC")
Mark Andrews's avatar
Mark Andrews committed
3
 * Copyright (C) 1999-2003  Internet Software Consortium.
4
 *
Automatic Updater's avatar
Automatic Updater committed
5
 * Permission to use, copy, modify, and/or distribute this software for any
Michael Graff's avatar
Michael Graff committed
6 7
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
8
 *
Mark Andrews's avatar
Mark Andrews committed
9 10 11 12 13 14 15
 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.
Michael Graff's avatar
Michael Graff committed
16
 */
17

Evan Hunt's avatar
Evan Hunt committed
18
/* $Id: adb.h,v 1.88 2011/12/05 17:10:51 each Exp $ */
David Lawrence's avatar
David Lawrence committed
19

Michael Graff's avatar
Michael Graff committed
20
#ifndef DNS_ADB_H
21
#define DNS_ADB_H 1
Michael Graff's avatar
Michael Graff committed
22

23 24 25
/*****
 ***** Module Info
 *****/
26

27
/*! \file dns/adb.h
28
 *\brief
29 30
 * DNS Address Database
 *
Bob Halley's avatar
Bob Halley committed
31 32 33
 * This module implements an address database (ADB) for mapping a name
 * to an isc_sockaddr_t. It also provides statistical information on
 * how good that address might be.
34
 *
35 36 37 38 39 40
 * A client will pass in a dns_name_t, and the ADB will walk through
 * the rdataset looking up addresses associated with the name.  If it
 * is found on the internal lists, a structure is filled in with the
 * address information and stats for found addresses.
 *
 * If the name cannot be found on the internal lists, a new entry will
Bob Halley's avatar
Bob Halley committed
41
 * be created for a name if all the information needed can be found
42 43
 * in the zone table or cache.  This new address will then be returned.
 *
44
 * If a request must be made to remote servers to satisfy a name lookup,
45 46 47 48 49 50
 * this module will start fetches to try to complete these addresses.  When
 * at least one more completes, an event is sent to the caller.  If none of
 * them resolve before the fetch times out, an event indicating this is
 * sent instead.
 *
 * Records are stored internally until a timer expires. The timer is the
51
 * smaller of the TTL or signature validity period.
52
 *
53 54 55
 * Lameness is stored per <qname,qtype> tuple, and this data hangs off each
 * address field.  When an address is marked lame for a given tuple the address
 * will not be returned to a caller.
56 57 58 59
 *
 *
 * MP:
 *
60
 *\li	The ADB takes care of all necessary locking.
61
 *
62
 *\li	Only the task which initiated the name lookup can cancel the lookup.
63 64 65 66
 *
 *
 * Security:
 *
67
 *\li	None, since all data stored is required to be pre-filtered.
68
 *	(Cache needs to be sane, fetches return bounds-checked and sanity-
Bob Halley's avatar
Bob Halley committed
69
 *       checked data, caller passes a good dns_name_t for the zone, etc)
70 71
 */

Michael Graff's avatar
Michael Graff committed
72
/***
Bob Halley's avatar
Bob Halley committed
73
 *** Imports
Michael Graff's avatar
Michael Graff committed
74 75 76
 ***/

#include <isc/lang.h>
Michael Graff's avatar
Michael Graff committed
77 78
#include <isc/magic.h>
#include <isc/mem.h>
79
#include <isc/sockaddr.h>
Michael Graff's avatar
Michael Graff committed
80

Bob Halley's avatar
Bob Halley committed
81
#include <dns/types.h>
Michael Graff's avatar
Michael Graff committed
82
#include <dns/view.h>
Michael Graff's avatar
Michael Graff committed
83 84

ISC_LANG_BEGINDECLS
85

Michael Graff's avatar
Michael Graff committed
86 87 88 89
/***
 *** Magic number checks
 ***/

90
#define DNS_ADBFIND_MAGIC	  ISC_MAGIC('a','d','b','H')
91
#define DNS_ADBFIND_VALID(x)	  ISC_MAGIC_VALID(x, DNS_ADBFIND_MAGIC)
92
#define DNS_ADBADDRINFO_MAGIC	  ISC_MAGIC('a','d','A','I')
Michael Graff's avatar
Michael Graff committed
93 94 95
#define DNS_ADBADDRINFO_VALID(x)  ISC_MAGIC_VALID(x, DNS_ADBADDRINFO_MAGIC)


96 97 98 99
/***
 *** TYPES
 ***/

Bob Halley's avatar
Bob Halley committed
100
typedef struct dns_adbname		dns_adbname_t;
101

Automatic Updater's avatar
Automatic Updater committed
102
/*!
103
 *\brief
Bob Halley's avatar
Bob Halley committed
104
 * Represents a lookup for a single name.
105 106 107 108
 *
 * On return, the client can safely use "list", and can reorder the list.
 * Items may not be _deleted_ from this list, however, or added to it
 * other than by using the dns_adb_*() API.
109
 */
110
struct dns_adbfind {
Michael Graff's avatar
Michael Graff committed
111
	/* Public */
112 113 114 115 116 117 118 119
	unsigned int			magic;		/*%< RO: magic */
	dns_adbaddrinfolist_t		list;		/*%< RO: list of addrs */
	unsigned int			query_pending;	/*%< RO: partial list */
	unsigned int			partial_result;	/*%< RO: addrs missing */
	unsigned int			options;	/*%< RO: options */
	isc_result_t			result_v4;	/*%< RO: v4 result */
	isc_result_t			result_v6;	/*%< RO: v6 result */
	ISC_LINK(dns_adbfind_t)		publink;	/*%< RW: client use */
Michael Graff's avatar
Michael Graff committed
120 121 122

	/* Private */
	isc_mutex_t			lock;		/* locks all below */
123
	in_port_t			port;
124
	int				name_bucket;
125
	unsigned int			flags;
126
	dns_adbname_t		       *adbname;
127
	dns_adb_t		       *adb;
Michael Graff's avatar
Michael Graff committed
128
	isc_event_t			event;
Bob Halley's avatar
Bob Halley committed
129
	ISC_LINK(dns_adbfind_t)		plink;
Michael Graff's avatar
Michael Graff committed
130
};
131

132 133 134 135 136 137 138 139 140 141 142 143 144 145
/*
 * _INET:
 * _INET6:
 *	return addresses of that type.
 *
 * _EMPTYEVENT:
 *	Only schedule an event if no addresses are known.
 *	Must set _WANTEVENT for this to be meaningful.
 *
 * _WANTEVENT:
 *	An event is desired.  Check this bit in the returned find to see
 *	if one will actually be generated.
 *
 * _AVOIDFETCHES:
Andreas Gustafsson's avatar
Andreas Gustafsson committed
146 147
 *	If set, fetches will not be generated unless no addresses are
 *	available in any of the address families requested.
148
 *
149 150 151
 * _STARTATZONE:
 *	Fetches will start using the closest zone data or use the root servers.
 *	This is useful for reestablishing glue that has expired.
152 153 154 155 156 157
 *
 * _GLUEOK:
 * _HINTOK:
 *	Glue or hints are ok.  These are used when matching names already
 *	in the adb, and when dns databases are searched.
 *
Michael Graff's avatar
Michael Graff committed
158 159
 * _RETURNLAME:
 *	Return lame servers in a find, so that all addresses are returned.
160 161 162
 *
 * _LAMEPRUNED:
 *	At least one address was omitted from the list because it was lame.
163
 *	This bit will NEVER be set if _RETURNLAME is set in the createfind().
164
 */
165
/*% Return addresses of type INET. */
Michael Graff's avatar
Michael Graff committed
166
#define DNS_ADBFIND_INET		0x00000001
167
/*% Return addresses of type INET6. */
Michael Graff's avatar
Michael Graff committed
168 169
#define DNS_ADBFIND_INET6		0x00000002
#define DNS_ADBFIND_ADDRESSMASK		0x00000003
170 171 172 173
/*%
 *      Only schedule an event if no addresses are known.
 *      Must set _WANTEVENT for this to be meaningful.
 */
174
#define DNS_ADBFIND_EMPTYEVENT		0x00000004
175 176 177 178
/*%
 *	An event is desired.  Check this bit in the returned find to see
 *	if one will actually be generated.
 */
179
#define DNS_ADBFIND_WANTEVENT		0x00000008
180 181 182 183
/*%
 *	If set, fetches will not be generated unless no addresses are
 *	available in any of the address families requested.
 */
Bob Halley's avatar
Bob Halley committed
184
#define DNS_ADBFIND_AVOIDFETCHES	0x00000010
185 186 187 188
/*%
 *	Fetches will start using the closest zone data or use the root servers.
 *	This is useful for reestablishing glue that has expired.
 */
189
#define DNS_ADBFIND_STARTATZONE		0x00000020
190 191 192 193
/*%
 *	Glue or hints are ok.  These are used when matching names already
 *	in the adb, and when dns databases are searched.
 */
194
#define DNS_ADBFIND_GLUEOK		0x00000040
195 196 197 198
/*%
 *	Glue or hints are ok.  These are used when matching names already
 *	in the adb, and when dns databases are searched.
 */
199
#define DNS_ADBFIND_HINTOK		0x00000080
200 201 202
/*%
 *	Return lame servers in a find, so that all addresses are returned.
 */
Michael Graff's avatar
Michael Graff committed
203
#define DNS_ADBFIND_RETURNLAME		0x00000100
204 205 206 207
/*%
 *      Only schedule an event if no addresses are known.
 *      Must set _WANTEVENT for this to be meaningful.
 */
208
#define DNS_ADBFIND_LAMEPRUNED		0x00000200
Michael Graff's avatar
Michael Graff committed
209

210
/*%
Michael Graff's avatar
Michael Graff committed
211 212 213
 * The answers to queries come back as a list of these.
 */
struct dns_adbaddrinfo {
214
	unsigned int			magic;		/*%< private */
Michael Graff's avatar
Michael Graff committed
215

216
	isc_sockaddr_t			sockaddr;	/*%< [rw] */
Evan Hunt's avatar
Evan Hunt committed
217 218 219
	unsigned int			srtt;		/*%< [rw] microsecs */
	isc_dscp_t			dscp;

220 221
	unsigned int			flags;		/*%< [rw] */
	dns_adbentry_t		       *entry;		/*%< private */
222
	ISC_LINK(dns_adbaddrinfo_t)	publink;
223 224
};

Automatic Updater's avatar
Automatic Updater committed
225
/*!<
226 227 228 229 230
 * The event sent to the caller task is just a plain old isc_event_t.  It
 * contains no data other than a simple status, passed in the "type" field
 * to indicate that another address resolved, or all partially resolved
 * addresses have failed to resolve.
 *
231
 * "sender" is the dns_adbfind_t used to issue this query.
232 233 234
 *
 * This is simply a standard event, with the "type" set to:
 *
235 236
 *\li	#DNS_EVENT_ADBMOREADDRESSES   -- another address resolved.
 *\li	#DNS_EVENT_ADBNOMOREADDRESSES -- all pending addresses failed,
237 238
 *					were canceled, or otherwise will
 *					not be usable.
239
 *\li	#DNS_EVENT_ADBCANCELED	     -- The request was canceled by a
240
 *					3rd party.
241
 *\li	#DNS_EVENT_ADBNAMEDELETED     -- The name was deleted, so this request
242 243 244
 *					was canceled.
 *
 * In each of these cases, the addresses returned by the initial call
245
 * to dns_adb_createfind() can still be used until they are no longer needed.
246 247 248 249 250 251
 */

/****
 **** FUNCTIONS
 ****/

Michael Graff's avatar
Michael Graff committed
252 253

isc_result_t
Michael Graff's avatar
fix  
Michael Graff committed
254
dns_adb_create(isc_mem_t *mem, dns_view_t *view, isc_timermgr_t *tmgr,
Michael Graff's avatar
Michael Graff committed
255
	       isc_taskmgr_t *taskmgr, dns_adb_t **newadb);
256
/*%<
257 258
 * Create a new ADB.
 *
Bob Halley's avatar
Bob Halley committed
259 260
 * Notes:
 *
261
 *\li	Generally, applications should not create an ADB directly, but
Bob Halley's avatar
Bob Halley committed
262 263
 *	should instead call dns_view_createresolver().
 *
264 265
 * Requires:
 *
266
 *\li	'mem' must be a valid memory context.
267
 *
268
 *\li	'view' be a pointer to a valid view.
Michael Graff's avatar
fix  
Michael Graff committed
269
 *
270
 *\li	'tmgr' be a pointer to a valid timer manager.
Michael Graff's avatar
Michael Graff committed
271
 *
272
 *\li	'taskmgr' be a pointer to a valid task manager.
Bob Halley's avatar
Bob Halley committed
273
 *
274
 *\li	'newadb' != NULL && '*newadb' == NULL.
Michael Graff's avatar
Michael Graff committed
275
 *
276 277
 * Returns:
 *
278 279
 *\li	#ISC_R_SUCCESS	after happiness.
 *\li	#ISC_R_NOMEMORY	after resource allocation failure.
280 281
 */

Mark Andrews's avatar
Mark Andrews committed
282 283
void
dns_adb_attach(dns_adb_t *adb, dns_adb_t **adbp);
284
/*%
Mark Andrews's avatar
Mark Andrews committed
285 286 287
 * Attach to an 'adb' to 'adbp'.
 *
 * Requires:
288 289
 *\li	'adb' to be a valid dns_adb_t, created via dns_adb_create().
 *\li	'adbp' to be a valid pointer to a *dns_adb_t which is initialized
Mark Andrews's avatar
Mark Andrews committed
290
 *	to NULL.
Mark Andrews's avatar
Mark Andrews committed
291 292
 */

Michael Graff's avatar
Michael Graff committed
293
void
294
dns_adb_detach(dns_adb_t **adb);
295
/*%
296 297 298 299
 * Delete the ADB. Sets *ADB to NULL. Cancels any outstanding requests.
 *
 * Requires:
 *
300
 *\li	'adb' be non-NULL and '*adb' be a valid dns_adb_t, created via
301 302 303
 *	dns_adb_create().
 */

304 305
void
dns_adb_whenshutdown(dns_adb_t *adb, isc_task_t *task, isc_event_t **eventp);
306
/*%
307 308 309 310
 * Send '*eventp' to 'task' when 'adb' has shutdown.
 *
 * Requires:
 *
311
 *\li	'*adb' is a valid dns_adb_t.
312
 *
313
 *\li	eventp != NULL && *eventp is a valid event.
314 315 316
 *
 * Ensures:
 *
317
 *\li	*eventp == NULL
318
 *
319
 *\li	The event's sender field is set to the value of adb when the event
320 321 322 323 324
 *	is sent.
 */

void
dns_adb_shutdown(dns_adb_t *adb);
325
/*%<
326 327 328 329
 * Shutdown 'adb'.
 *
 * Requires:
 *
330
 * \li	'*adb' is a valid dns_adb_t.
331
 */
332

Michael Graff's avatar
Michael Graff committed
333
isc_result_t
334
dns_adb_createfind(dns_adb_t *adb, isc_task_t *task, isc_taskaction_t action,
335 336 337
		   void *arg, dns_name_t *name, dns_name_t *qname,
		   dns_rdatatype_t qtype, unsigned int options,
		   isc_stdtime_t now, dns_name_t *target,
338
		   in_port_t port, dns_adbfind_t **find);
339
/*%<
Michael Graff's avatar
Michael Graff committed
340 341
 * Main interface for clients. The adb will look up the name given in
 * "name" and will build up a list of found addresses, and perhaps start
342 343 344 345
 * internal fetches to resolve names that are unknown currently.
 *
 * If other addresses resolve after this call completes, an event will
 * be sent to the <task, taskaction, arg> with the sender of that event
346
 * set to a pointer to the dns_adbfind_t returned by this function.
347
 *
Michael Graff's avatar
Michael Graff committed
348
 * If no events will be generated, the *find->result_v4 and/or result_v6
349
 * members may be examined for address lookup status.  The usual #ISC_R_SUCCESS,
350
 * #ISC_R_FAILURE, #DNS_R_NXDOMAIN, and #DNS_R_NXRRSET are returned, along with
351
 * #ISC_R_NOTFOUND meaning the ADB has not _yet_ found the values.  In this
Michael Graff's avatar
Michael Graff committed
352 353 354 355 356
 * latter case, retrying may produce more addresses.
 *
 * If events will be returned, the result_v[46] members are only valid
 * when that event is actually returned.
 *
357 358 359 360 361 362 363 364 365
 * The list of addresses returned is unordered.  The caller must impose
 * any ordering required.  The list will not contain "known bad" addresses,
 * however.  For instance, it will not return hosts that are known to be
 * lame for the zone in question.
 *
 * The caller cannot (directly) modify the contents of the address list's
 * fields other than the "link" field.  All values can be read at any
 * time, however.
 *
Michael Graff's avatar
Michael Graff committed
366 367 368 369 370
 * The "now" parameter is used only for determining which entries that
 * have a specific time to live or expire time should be removed from
 * the running database.  If specified as zero, the current time will
 * be retrieved and used.
 *
371 372 373 374
 * If 'target' is not NULL and 'name' is an alias (i.e. the name is
 * CNAME'd or DNAME'd to another name), then 'target' will be updated with
 * the domain name that 'name' is aliased to.
 *
375 376 377 378
 * All addresses returned will have the sockaddr's port set to 'port.'
 * The caller may change them directly in the dns_adbaddrinfo_t since
 * they are copies of the internal address only.
 *
Bob Halley's avatar
Bob Halley committed
379 380 381
 * XXXMLG  Document options, especially the flags which control how
 *         events are sent.
 *
382 383
 * Requires:
 *
384
 *\li	*adb be a valid isc_adb_t object.
385
 *
386
 *\li	If events are to be sent, *task be a valid task,
Michael Graff's avatar
Michael Graff committed
387
 *	and isc_taskaction_t != NULL.
388
 *
389
 *\li	*name is a valid dns_name_t.
390
 *
391
 *\li	qname != NULL and *qname be a valid dns_name_t.
392
 *
393
 *\li	target == NULL or target is a valid name with a buffer.
394
 *
395
 *\li	find != NULL && *find == NULL.
396 397 398
 *
 * Returns:
 *
399
 *\li	#ISC_R_SUCCESS	Addresses might have been returned, and events will be
400
 *			delivered for unresolved addresses.
401
 *\li	#ISC_R_NOMORE	Addresses might have been returned, but no events
Michael Graff's avatar
Michael Graff committed
402 403
 *			will ever be posted for this context.  This is only
 *			returned if task != NULL.
404 405
 *\li	#ISC_R_NOMEMORY	insufficient resources
 *\li	#DNS_R_ALIAS	'name' is an alias for another name.
406
 *
Michael Graff's avatar
Michael Graff committed
407 408
 * Calls, and returns error codes from:
 *
409
 *\li	isc_stdtime_get()
Michael Graff's avatar
Michael Graff committed
410
 *
Michael Graff's avatar
Michael Graff committed
411
 * Notes:
412
 *
413
 *\li	No internal reference to "name" exists after this function
414 415 416
 *	returns.
 */

Michael Graff's avatar
Michael Graff committed
417
void
418
dns_adb_cancelfind(dns_adbfind_t *find);
419
/*%<
420 421
 * Cancels the find, and sends the event off to the caller.
 *
422
 * It is an error to call dns_adb_cancelfind() on a find where
423
 * no event is wanted, or will ever be sent.
424
 *
Bob Halley's avatar
Bob Halley committed
425 426
 * Note:
 *
427
 *\li	It is possible that the real completion event was posted just
Bob Halley's avatar
Bob Halley committed
428 429 430 431 432
 *	before the dns_adb_cancelfind() call was made.  In this case,
 *	dns_adb_cancelfind() will do nothing.  The event callback needs
 *	to be prepared to find this situation (i.e. result is valid but
 *	the caller expects it to be canceled).
 *
433 434
 * Requires:
 *
435
 *\li	'find' be a valid dns_adbfind_t pointer.
436
 *
437
 *\li	events would have been posted to the task.  This can be checked
438
 *	with (find->options & DNS_ADBFIND_WANTEVENT).
439 440 441
 *
 * Ensures:
 *
442
 *\li	The event was posted to the task.
443 444 445
 */

void
446
dns_adb_destroyfind(dns_adbfind_t **find);
447
/*%<
448
 * Destroys the find reference.
449
 *
Bob Halley's avatar
Bob Halley committed
450 451
 * Note:
 *
452
 *\li	This can only be called after the event was delivered for a
Bob Halley's avatar
Bob Halley committed
453 454 455
 *	find.  Additionally, the event MUST have been freed via
 *	isc_event_free() BEFORE this function is called.
 *
456
 * Requires:
457
 *
458
 *\li	'find' != NULL and *find be valid dns_adbfind_t pointer.
459 460 461
 *
 * Ensures:
 *
462
 *\li	No "address found" events will be posted to the originating task
463 464 465
 *	after this function returns.
 */

Michael Graff's avatar
Michael Graff committed
466 467
void
dns_adb_dump(dns_adb_t *adb, FILE *f);
468
/*%<
Bob Halley's avatar
Bob Halley committed
469
 * This function is only used for debugging.  It will dump as much of the
Michael Graff's avatar
Michael Graff committed
470 471 472 473
 * state of the running system as possible.
 *
 * Requires:
 *
474
 *\li	adb be valid.
Michael Graff's avatar
Michael Graff committed
475
 *
476
 *\li	f != NULL, and is a file open for writing.
Michael Graff's avatar
Michael Graff committed
477 478
 */

479
void
480
dns_adb_dumpfind(dns_adbfind_t *find, FILE *f);
481
/*%<
Bob Halley's avatar
Bob Halley committed
482 483
 * This function is only used for debugging.  Dump the data associated
 * with a find.
484 485 486
 *
 * Requires:
 *
487
 *\li	find is valid.
488
 *
489
 * \li	f != NULL, and is a file open for writing.
490 491
 */

492
isc_result_t
493 494
dns_adb_marklame(dns_adb_t *adb, dns_adbaddrinfo_t *addr, dns_name_t *qname,
		 dns_rdatatype_t type, isc_stdtime_t expire_time);
495
/*%<
496
 * Mark the given address as lame for the <qname,qtype>.  expire_time should
Michael Graff's avatar
Michael Graff committed
497 498
 * be set to the time when the entry should expire.  That is, if it is to
 * expire 10 minutes in the future, it should set it to (now + 10 * 60).
499 500 501
 *
 * Requires:
 *
502
 *\li	adb be valid.
503
 *
504
 *\li	addr be valid.
505
 *
506
 *\li	qname be the qname used in the dns_adb_createfind() call.
507 508 509
 *
 * Returns:
 *
510 511
 *\li	#ISC_R_SUCCESS		-- all is well.
 *\li	#ISC_R_NOMEMORY		-- could not mark address as lame.
512
 */
513

514 515 516
/*
 * A reasonable default for RTT adjustments
 */
517 518 519
#define DNS_ADB_RTTADJDEFAULT		7	/*%< default scale */
#define DNS_ADB_RTTADJREPLACE		0	/*%< replace with our rtt */
#define DNS_ADB_RTTADJAGE		10	/*%< age this rtt */
520

521 522 523
void
dns_adb_adjustsrtt(dns_adb_t *adb, dns_adbaddrinfo_t *addr,
		   unsigned int rtt, unsigned int factor);
524
/*%<
Automatic Updater's avatar
Automatic Updater committed
525
 * Mix the round trip time into the existing smoothed rtt.
526 527

 * The formula used
528 529 530
 * (where srtt is the existing rtt value, and rtt and factor are arguments to
 * this function):
 *
531
 *\code
532
 *	new_srtt = (old_srtt / 10 * factor) + (rtt / 10 * (10 - factor));
533
 *\endcode
534
 *
Bob Halley's avatar
Bob Halley committed
535 536 537 538
 * XXXRTH  Do we want to publish the formula?  What if we want to change how
 *         this works later on?  Recommend/require that the units are
 *	   microseconds?
 *
539 540
 * Requires:
 *
541
 *\li	adb be valid.
542
 *
543
 *\li	addr be valid.
544
 *
545
 *\li	0 <= factor <= 10
546
 *
547
 * Note:
548
 *
549
 *\li	The srtt in addr will be updated to reflect the new global
550 551 552
 *	srtt value.  This may include changes made by others.
 */

Michael Graff's avatar
Michael Graff committed
553 554 555
void
dns_adb_changeflags(dns_adb_t *adb, dns_adbaddrinfo_t *addr,
		    unsigned int bits, unsigned int mask);
556 557 558
/*%
 * Change Flags.
 *
Michael Graff's avatar
Michael Graff committed
559 560
 * Set the flags as given by:
 *
561
 *\li	newflags = (oldflags & ~mask) | (bits & mask);
Michael Graff's avatar
Michael Graff committed
562 563 564
 *
 * Requires:
 *
565
 *\li	adb be valid.
Michael Graff's avatar
Michael Graff committed
566
 *
567
 *\li	addr be valid.
Michael Graff's avatar
Michael Graff committed
568
 */
569

570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656
void
dns_adb_setudpsize(dns_adb_t *adb, dns_adbaddrinfo_t *addr, unsigned int size);
/*%
 * Update seen UDP response size.  The largest seen will be returned by
 * dns_adb_getudpsize().
 *
 * Requires:
 *
 *\li	adb be valid.
 *
 *\li	addr be valid.
 */

unsigned int
dns_adb_getudpsize(dns_adb_t *adb, dns_adbaddrinfo_t *addr);
/*%
 * Return the largest seen UDP response size.
 *
 * Requires:
 *
 *\li	adb be valid.
 *
 *\li	addr be valid.
 */

unsigned int
dns_adb_probesize(dns_adb_t *adb, dns_adbaddrinfo_t *addr);
/*%
 * Return suggested EDNS UDP size based on observed responses / failures.
 *
 * Requires:
 *
 *\li	adb be valid.
 *
 *\li	addr be valid.
 */

void
dns_adb_plainresponse(dns_adb_t *adb, dns_adbaddrinfo_t *addr);
/*%
 * Record a successful plain DNS response.
 *
 * Requires:
 *
 *\li	adb be valid.
 *
 *\li	addr be valid.
 */

void
dns_adb_timeout(dns_adb_t *adb, dns_adbaddrinfo_t *addr);
/*%
 * Record a plain DNS UDP query failed.
 *
 * Requires:
 *
 *\li	adb be valid.
 *
 *\li	addr be valid.
 */

void
dns_adb_ednsto(dns_adb_t *adb, dns_adbaddrinfo_t *addr, unsigned int size);
/*%
 * Record a failed EDNS UDP response and the advertised EDNS UDP buffer size
 * used.
 *
 * Requires:
 *
 *\li	adb be valid.
 *
 *\li	addr be valid.
 */

isc_boolean_t
dns_adb_noedns(dns_adb_t *adb, dns_adbaddrinfo_t *addr);
/*%
 * Return whether EDNS should be disabled for this server.
 *
 * Requires:
 *
 *\li	adb be valid.
 *
 *\li	addr be valid.
 */


657 658
isc_result_t
dns_adb_findaddrinfo(dns_adb_t *adb, isc_sockaddr_t *sa,
659
		     dns_adbaddrinfo_t **addrp, isc_stdtime_t now);
660
/*%<
661 662 663 664
 * Return a dns_adbaddrinfo_t that is associated with address 'sa'.
 *
 * Requires:
 *
665
 *\li	adb is valid.
666
 *
667
 *\li	sa is valid.
668
 *
669
 *\li	addrp != NULL && *addrp == NULL
670 671
 *
 * Returns:
672 673 674
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_NOMEMORY
 *\li	#ISC_R_SHUTTINGDOWN
675 676 677 678
 */

void
dns_adb_freeaddrinfo(dns_adb_t *adb, dns_adbaddrinfo_t **addrp);
679
/*%<
680 681 682 683
 * Free a dns_adbaddrinfo_t allocated by dns_adb_findaddrinfo().
 *
 * Requires:
 *
684
 *\li	adb is valid.
685
 *
686
 *\li	*addrp is a valid dns_adbaddrinfo_t *.
687 688
 */

689 690
void
dns_adb_flush(dns_adb_t *adb);
691
/*%<
692 693 694
 * Flushes all cached data from the adb.
 *
 * Requires:
695
 *\li 	adb is valid.
696 697
 */

698
void
699
dns_adb_setadbsize(dns_adb_t *adb, size_t size);
700
/*%<
701 702 703 704 705 706 707
 * Set a target memory size.  If memory usage exceeds the target
 * size entries will be removed before they would have expired on
 * a random basis.
 *
 * If 'size' is 0 then memory usage is unlimited.
 *
 * Requires:
708
 *\li	'adb' is valid.
709 710
 */

711 712
void
dns_adb_flushname(dns_adb_t *adb, dns_name_t *name);
713
/*%<
714
 * Flush 'name' from the adb cache.
Automatic Updater's avatar
Automatic Updater committed
715
 *
716
 * Requires:
717 718
 *\li	'adb' is valid.
 *\li	'name' is valid.
719 720
 */

721 722 723 724 725 726 727 728 729 730
void
dns_adb_flushnames(dns_adb_t *adb, dns_name_t *name);
/*%<
 * Flush 'name' and all subdomains from the adb cache.
 *
 * Requires:
 *\li	'adb' is valid.
 *\li	'name' is valid.
 */

731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756
void
dns_adb_setsit(dns_adb_t *adb, dns_adbaddrinfo_t *addr,
	       const unsigned char *sit, size_t len);
/*%<
 * Record the Source Identity Token (SIT) associated with this addresss.  If
 * sit is NULL or len is zero. The recorded SIT is cleared.
 *
 * Requires:
 *\li	'adb' is valid.
 *\li	'addr' is valid.
 */

size_t
dns_adb_getsit(dns_adb_t *adb, dns_adbaddrinfo_t *addr,
	       unsigned char *sit, size_t len);
/*
 * Retieve the saved SIT value and store it in 'sit' which has size 'len'.
 *
 * Requires:
 *\li	'adb' is valid.
 *\li	'addr' is valid.
 *
 * Returns:
 *	The size of the sit token or zero if it doesn't fit in the buffer
 *	or it doesn't exist.
 */
757

Michael Graff's avatar
Michael Graff committed
758 759
ISC_LANG_ENDDECLS

Michael Graff's avatar
Michael Graff committed
760
#endif /* DNS_ADB_H */