/contrib/bind9/lib/dns/include/dns/resolver.h

https://bitbucket.org/freebsd/freebsd-head/ · C Header · 577 lines · 164 code · 59 blank · 354 comment · 0 complexity · d3d75e867adef74da0fdf113abc36358 MD5 · raw file

  1. /*
  2. * Copyright (C) 2004-2012 Internet Systems Consortium, Inc. ("ISC")
  3. * Copyright (C) 1999-2001, 2003 Internet Software Consortium.
  4. *
  5. * Permission to use, copy, modify, and/or distribute this software for any
  6. * purpose with or without fee is hereby granted, provided that the above
  7. * copyright notice and this permission notice appear in all copies.
  8. *
  9. * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10. * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11. * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12. * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13. * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14. * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15. * PERFORMANCE OF THIS SOFTWARE.
  16. */
  17. /* $Id$ */
  18. #ifndef DNS_RESOLVER_H
  19. #define DNS_RESOLVER_H 1
  20. /*****
  21. ***** Module Info
  22. *****/
  23. /*! \file dns/resolver.h
  24. *
  25. * \brief
  26. * This is the BIND 9 resolver, the module responsible for resolving DNS
  27. * requests by iteratively querying authoritative servers and following
  28. * referrals. This is a "full resolver", not to be confused with
  29. * the stub resolvers most people associate with the word "resolver".
  30. * The full resolver is part of the caching name server or resolver
  31. * daemon the stub resolver talks to.
  32. *
  33. * MP:
  34. *\li The module ensures appropriate synchronization of data structures it
  35. * creates and manipulates.
  36. *
  37. * Reliability:
  38. *\li No anticipated impact.
  39. *
  40. * Resources:
  41. *\li TBS
  42. *
  43. * Security:
  44. *\li No anticipated impact.
  45. *
  46. * Standards:
  47. *\li RFCs: 1034, 1035, 2181, TBS
  48. *\li Drafts: TBS
  49. */
  50. #include <isc/lang.h>
  51. #include <isc/socket.h>
  52. #include <dns/types.h>
  53. #include <dns/fixedname.h>
  54. ISC_LANG_BEGINDECLS
  55. /*%
  56. * A dns_fetchevent_t is sent when a 'fetch' completes. Any of 'db',
  57. * 'node', 'rdataset', and 'sigrdataset' may be bound. It is the
  58. * receiver's responsibility to detach before freeing the event.
  59. * \brief
  60. * 'rdataset', 'sigrdataset', 'client' and 'id' are the values that were
  61. * supplied when dns_resolver_createfetch() was called. They are returned
  62. * to the caller so that they may be freed.
  63. */
  64. typedef struct dns_fetchevent {
  65. ISC_EVENT_COMMON(struct dns_fetchevent);
  66. dns_fetch_t * fetch;
  67. isc_result_t result;
  68. dns_rdatatype_t qtype;
  69. dns_db_t * db;
  70. dns_dbnode_t * node;
  71. dns_rdataset_t * rdataset;
  72. dns_rdataset_t * sigrdataset;
  73. dns_fixedname_t foundname;
  74. isc_sockaddr_t * client;
  75. dns_messageid_t id;
  76. isc_result_t vresult;
  77. } dns_fetchevent_t;
  78. /*
  79. * Options that modify how a 'fetch' is done.
  80. */
  81. #define DNS_FETCHOPT_TCP 0x01 /*%< Use TCP. */
  82. #define DNS_FETCHOPT_UNSHARED 0x02 /*%< See below. */
  83. #define DNS_FETCHOPT_RECURSIVE 0x04 /*%< Set RD? */
  84. #define DNS_FETCHOPT_NOEDNS0 0x08 /*%< Do not use EDNS. */
  85. #define DNS_FETCHOPT_FORWARDONLY 0x10 /*%< Only use forwarders. */
  86. #define DNS_FETCHOPT_NOVALIDATE 0x20 /*%< Disable validation. */
  87. #define DNS_FETCHOPT_EDNS512 0x40 /*%< Advertise a 512 byte
  88. UDP buffer. */
  89. #define DNS_FETCHOPT_WANTNSID 0x80 /*%< Request NSID */
  90. #define DNS_FETCHOPT_EDNSVERSIONSET 0x00800000
  91. #define DNS_FETCHOPT_EDNSVERSIONMASK 0xff000000
  92. #define DNS_FETCHOPT_EDNSVERSIONSHIFT 24
  93. /*
  94. * Upper bounds of class of query RTT (ms). Corresponds to
  95. * dns_resstatscounter_queryrttX statistics counters.
  96. */
  97. #define DNS_RESOLVER_QRYRTTCLASS0 10
  98. #define DNS_RESOLVER_QRYRTTCLASS0STR "10"
  99. #define DNS_RESOLVER_QRYRTTCLASS1 100
  100. #define DNS_RESOLVER_QRYRTTCLASS1STR "100"
  101. #define DNS_RESOLVER_QRYRTTCLASS2 500
  102. #define DNS_RESOLVER_QRYRTTCLASS2STR "500"
  103. #define DNS_RESOLVER_QRYRTTCLASS3 800
  104. #define DNS_RESOLVER_QRYRTTCLASS3STR "800"
  105. #define DNS_RESOLVER_QRYRTTCLASS4 1600
  106. #define DNS_RESOLVER_QRYRTTCLASS4STR "1600"
  107. /*
  108. * XXXRTH Should this API be made semi-private? (I.e.
  109. * _dns_resolver_create()).
  110. */
  111. #define DNS_RESOLVER_CHECKNAMES 0x01
  112. #define DNS_RESOLVER_CHECKNAMESFAIL 0x02
  113. isc_result_t
  114. dns_resolver_create(dns_view_t *view,
  115. isc_taskmgr_t *taskmgr, unsigned int ntasks,
  116. isc_socketmgr_t *socketmgr,
  117. isc_timermgr_t *timermgr,
  118. unsigned int options,
  119. dns_dispatchmgr_t *dispatchmgr,
  120. dns_dispatch_t *dispatchv4,
  121. dns_dispatch_t *dispatchv6,
  122. dns_resolver_t **resp);
  123. /*%<
  124. * Create a resolver.
  125. *
  126. * Notes:
  127. *
  128. *\li Generally, applications should not create a resolver directly, but
  129. * should instead call dns_view_createresolver().
  130. *
  131. * Requires:
  132. *
  133. *\li 'view' is a valid view.
  134. *
  135. *\li 'taskmgr' is a valid task manager.
  136. *
  137. *\li 'ntasks' > 0.
  138. *
  139. *\li 'socketmgr' is a valid socket manager.
  140. *
  141. *\li 'timermgr' is a valid timer manager.
  142. *
  143. *\li 'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL.
  144. *
  145. *\li 'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL.
  146. *
  147. *\li resp != NULL && *resp == NULL.
  148. *
  149. * Returns:
  150. *
  151. *\li #ISC_R_SUCCESS On success.
  152. *
  153. *\li Anything else Failure.
  154. */
  155. void
  156. dns_resolver_freeze(dns_resolver_t *res);
  157. /*%<
  158. * Freeze resolver.
  159. *
  160. * Notes:
  161. *
  162. *\li Certain configuration changes cannot be made after the resolver
  163. * is frozen. Fetches cannot be created until the resolver is frozen.
  164. *
  165. * Requires:
  166. *
  167. *\li 'res' is a valid resolver.
  168. *
  169. * Ensures:
  170. *
  171. *\li 'res' is frozen.
  172. */
  173. void
  174. dns_resolver_prime(dns_resolver_t *res);
  175. /*%<
  176. * Prime resolver.
  177. *
  178. * Notes:
  179. *
  180. *\li Resolvers which have a forwarding policy other than dns_fwdpolicy_only
  181. * need to be primed with the root nameservers, otherwise the root
  182. * nameserver hints data may be used indefinitely. This function requests
  183. * that the resolver start a priming fetch, if it isn't already priming.
  184. *
  185. * Requires:
  186. *
  187. *\li 'res' is a valid, frozen resolver.
  188. */
  189. void
  190. dns_resolver_whenshutdown(dns_resolver_t *res, isc_task_t *task,
  191. isc_event_t **eventp);
  192. /*%<
  193. * Send '*eventp' to 'task' when 'res' has completed shutdown.
  194. *
  195. * Notes:
  196. *
  197. *\li It is not safe to detach the last reference to 'res' until
  198. * shutdown is complete.
  199. *
  200. * Requires:
  201. *
  202. *\li 'res' is a valid resolver.
  203. *
  204. *\li 'task' is a valid task.
  205. *
  206. *\li *eventp is a valid event.
  207. *
  208. * Ensures:
  209. *
  210. *\li *eventp == NULL.
  211. */
  212. void
  213. dns_resolver_shutdown(dns_resolver_t *res);
  214. /*%<
  215. * Start the shutdown process for 'res'.
  216. *
  217. * Notes:
  218. *
  219. *\li This call has no effect if the resolver is already shutting down.
  220. *
  221. * Requires:
  222. *
  223. *\li 'res' is a valid resolver.
  224. */
  225. void
  226. dns_resolver_attach(dns_resolver_t *source, dns_resolver_t **targetp);
  227. void
  228. dns_resolver_detach(dns_resolver_t **resp);
  229. isc_result_t
  230. dns_resolver_createfetch(dns_resolver_t *res, dns_name_t *name,
  231. dns_rdatatype_t type,
  232. dns_name_t *domain, dns_rdataset_t *nameservers,
  233. dns_forwarders_t *forwarders,
  234. unsigned int options, isc_task_t *task,
  235. isc_taskaction_t action, void *arg,
  236. dns_rdataset_t *rdataset,
  237. dns_rdataset_t *sigrdataset,
  238. dns_fetch_t **fetchp);
  239. isc_result_t
  240. dns_resolver_createfetch2(dns_resolver_t *res, dns_name_t *name,
  241. dns_rdatatype_t type,
  242. dns_name_t *domain, dns_rdataset_t *nameservers,
  243. dns_forwarders_t *forwarders,
  244. isc_sockaddr_t *client, isc_uint16_t id,
  245. unsigned int options, isc_task_t *task,
  246. isc_taskaction_t action, void *arg,
  247. dns_rdataset_t *rdataset,
  248. dns_rdataset_t *sigrdataset,
  249. dns_fetch_t **fetchp);
  250. /*%<
  251. * Recurse to answer a question.
  252. *
  253. * Notes:
  254. *
  255. *\li This call starts a query for 'name', type 'type'.
  256. *
  257. *\li The 'domain' is a parent domain of 'name' for which
  258. * a set of name servers 'nameservers' is known. If no
  259. * such name server information is available, set
  260. * 'domain' and 'nameservers' to NULL.
  261. *
  262. *\li 'forwarders' is unimplemented, and subject to change when
  263. * we figure out how selective forwarding will work.
  264. *
  265. *\li When the fetch completes (successfully or otherwise), a
  266. * #DNS_EVENT_FETCHDONE event with action 'action' and arg 'arg' will be
  267. * posted to 'task'.
  268. *
  269. *\li The values of 'rdataset' and 'sigrdataset' will be returned in
  270. * the FETCHDONE event.
  271. *
  272. *\li 'client' and 'id' are used for duplicate query detection. '*client'
  273. * must remain stable until after 'action' has been called or
  274. * dns_resolver_cancelfetch() is called.
  275. *
  276. * Requires:
  277. *
  278. *\li 'res' is a valid resolver that has been frozen.
  279. *
  280. *\li 'name' is a valid name.
  281. *
  282. *\li 'type' is not a meta type other than ANY.
  283. *
  284. *\li 'domain' is a valid name or NULL.
  285. *
  286. *\li 'nameservers' is a valid NS rdataset (whose owner name is 'domain')
  287. * iff. 'domain' is not NULL.
  288. *
  289. *\li 'forwarders' is NULL.
  290. *
  291. *\li 'client' is a valid sockaddr or NULL.
  292. *
  293. *\li 'options' contains valid options.
  294. *
  295. *\li 'rdataset' is a valid, disassociated rdataset.
  296. *
  297. *\li 'sigrdataset' is NULL, or is a valid, disassociated rdataset.
  298. *
  299. *\li fetchp != NULL && *fetchp == NULL.
  300. *
  301. * Returns:
  302. *
  303. *\li #ISC_R_SUCCESS Success
  304. *\li #DNS_R_DUPLICATE
  305. *\li #DNS_R_DROP
  306. *
  307. *\li Many other values are possible, all of which indicate failure.
  308. */
  309. void
  310. dns_resolver_cancelfetch(dns_fetch_t *fetch);
  311. /*%<
  312. * Cancel 'fetch'.
  313. *
  314. * Notes:
  315. *
  316. *\li If 'fetch' has not completed, post its FETCHDONE event with a
  317. * result code of #ISC_R_CANCELED.
  318. *
  319. * Requires:
  320. *
  321. *\li 'fetch' is a valid fetch.
  322. */
  323. void
  324. dns_resolver_destroyfetch(dns_fetch_t **fetchp);
  325. /*%<
  326. * Destroy 'fetch'.
  327. *
  328. * Requires:
  329. *
  330. *\li '*fetchp' is a valid fetch.
  331. *
  332. *\li The caller has received the FETCHDONE event (either because the
  333. * fetch completed or because dns_resolver_cancelfetch() was called).
  334. *
  335. * Ensures:
  336. *
  337. *\li *fetchp == NULL.
  338. */
  339. void
  340. dns_resolver_logfetch(dns_fetch_t *fetch, isc_log_t *lctx,
  341. isc_logcategory_t *category, isc_logmodule_t *module,
  342. int level, isc_boolean_t duplicateok);
  343. /*%<
  344. * Dump a log message on internal state at the completion of given 'fetch'.
  345. * 'lctx', 'category', 'module', and 'level' are used to write the log message.
  346. * By default, only one log message is written even if the corresponding fetch
  347. * context serves multiple clients; if 'duplicateok' is true the suppression
  348. * is disabled and the message can be written every time this function is
  349. * called.
  350. *
  351. * Requires:
  352. *
  353. *\li 'fetch' is a valid fetch, and has completed.
  354. */
  355. dns_dispatchmgr_t *
  356. dns_resolver_dispatchmgr(dns_resolver_t *resolver);
  357. dns_dispatch_t *
  358. dns_resolver_dispatchv4(dns_resolver_t *resolver);
  359. dns_dispatch_t *
  360. dns_resolver_dispatchv6(dns_resolver_t *resolver);
  361. isc_socketmgr_t *
  362. dns_resolver_socketmgr(dns_resolver_t *resolver);
  363. isc_taskmgr_t *
  364. dns_resolver_taskmgr(dns_resolver_t *resolver);
  365. isc_uint32_t
  366. dns_resolver_getlamettl(dns_resolver_t *resolver);
  367. /*%<
  368. * Get the resolver's lame-ttl. zero => no lame processing.
  369. *
  370. * Requires:
  371. *\li 'resolver' to be valid.
  372. */
  373. void
  374. dns_resolver_setlamettl(dns_resolver_t *resolver, isc_uint32_t lame_ttl);
  375. /*%<
  376. * Set the resolver's lame-ttl. zero => no lame processing.
  377. *
  378. * Requires:
  379. *\li 'resolver' to be valid.
  380. */
  381. unsigned int
  382. dns_resolver_nrunning(dns_resolver_t *resolver);
  383. /*%<
  384. * Return the number of currently running resolutions in this
  385. * resolver. This is may be less than the number of outstanding
  386. * fetches due to multiple identical fetches, or more than the
  387. * number of of outstanding fetches due to the fact that resolution
  388. * can continue even though a fetch has been canceled.
  389. */
  390. isc_result_t
  391. dns_resolver_addalternate(dns_resolver_t *resolver, isc_sockaddr_t *alt,
  392. dns_name_t *name, in_port_t port);
  393. /*%<
  394. * Add alternate addresses to be tried in the event that the nameservers
  395. * for a zone are not available in the address families supported by the
  396. * operating system.
  397. *
  398. * Require:
  399. * \li only one of 'name' or 'alt' to be valid.
  400. */
  401. void
  402. dns_resolver_setudpsize(dns_resolver_t *resolver, isc_uint16_t udpsize);
  403. /*%<
  404. * Set the EDNS UDP buffer size advertised by the server.
  405. */
  406. isc_uint16_t
  407. dns_resolver_getudpsize(dns_resolver_t *resolver);
  408. /*%<
  409. * Get the current EDNS UDP buffer size.
  410. */
  411. void
  412. dns_resolver_reset_algorithms(dns_resolver_t *resolver);
  413. /*%<
  414. * Clear the disabled DNSSEC algorithms.
  415. */
  416. isc_result_t
  417. dns_resolver_disable_algorithm(dns_resolver_t *resolver, dns_name_t *name,
  418. unsigned int alg);
  419. /*%<
  420. * Mark the give DNSSEC algorithm as disabled and below 'name'.
  421. * Valid algorithms are less than 256.
  422. *
  423. * Returns:
  424. *\li #ISC_R_SUCCESS
  425. *\li #ISC_R_RANGE
  426. *\li #ISC_R_NOMEMORY
  427. */
  428. isc_boolean_t
  429. dns_resolver_algorithm_supported(dns_resolver_t *resolver, dns_name_t *name,
  430. unsigned int alg);
  431. /*%<
  432. * Check if the given algorithm is supported by this resolver.
  433. * This checks if the algorithm has been disabled via
  434. * dns_resolver_disable_algorithm() then the underlying
  435. * crypto libraries if not specifically disabled.
  436. */
  437. isc_boolean_t
  438. dns_resolver_digest_supported(dns_resolver_t *resolver, unsigned int digest_type);
  439. /*%<
  440. * Is this digest type supported.
  441. */
  442. void
  443. dns_resolver_resetmustbesecure(dns_resolver_t *resolver);
  444. isc_result_t
  445. dns_resolver_setmustbesecure(dns_resolver_t *resolver, dns_name_t *name,
  446. isc_boolean_t value);
  447. isc_boolean_t
  448. dns_resolver_getmustbesecure(dns_resolver_t *resolver, dns_name_t *name);
  449. void
  450. dns_resolver_settimeout(dns_resolver_t *resolver, unsigned int seconds);
  451. /*%<
  452. * Set the length of time the resolver will work on a query, in seconds.
  453. *
  454. * If timeout is 0, the default timeout will be applied.
  455. *
  456. * Requires:
  457. * \li resolver to be valid.
  458. */
  459. unsigned int
  460. dns_resolver_gettimeout(dns_resolver_t *resolver);
  461. /*%<
  462. * Get the current length of time the resolver will work on a query, in seconds.
  463. *
  464. * Requires:
  465. * \li resolver to be valid.
  466. */
  467. void
  468. dns_resolver_setclientsperquery(dns_resolver_t *resolver,
  469. isc_uint32_t min, isc_uint32_t max);
  470. void
  471. dns_resolver_getclientsperquery(dns_resolver_t *resolver, isc_uint32_t *cur,
  472. isc_uint32_t *min, isc_uint32_t *max);
  473. isc_boolean_t
  474. dns_resolver_getzeronosoattl(dns_resolver_t *resolver);
  475. void
  476. dns_resolver_setzeronosoattl(dns_resolver_t *resolver, isc_boolean_t state);
  477. unsigned int
  478. dns_resolver_getoptions(dns_resolver_t *resolver);
  479. void
  480. dns_resolver_addbadcache(dns_resolver_t *resolver, dns_name_t *name,
  481. dns_rdatatype_t type, isc_time_t *expire);
  482. /*%<
  483. * Add a entry to the bad cache for <name,type> that will expire at 'expire'.
  484. *
  485. * Requires:
  486. * \li resolver to be valid.
  487. * \li name to be valid.
  488. */
  489. isc_boolean_t
  490. dns_resolver_getbadcache(dns_resolver_t *resolver, dns_name_t *name,
  491. dns_rdatatype_t type, isc_time_t *now);
  492. /*%<
  493. * Check to see if there is a unexpired entry in the bad cache for
  494. * <name,type>.
  495. *
  496. * Requires:
  497. * \li resolver to be valid.
  498. * \li name to be valid.
  499. */
  500. void
  501. dns_resolver_flushbadcache(dns_resolver_t *resolver, dns_name_t *name);
  502. /*%<
  503. * Flush the bad cache of all entries at 'name' if 'name' is non NULL.
  504. * Flush the entire bad cache if 'name' is NULL.
  505. *
  506. * Requires:
  507. * \li resolver to be valid.
  508. */
  509. void
  510. dns_resolver_printbadcache(dns_resolver_t *resolver, FILE *fp);
  511. /*%
  512. * Print out the contents of the bad cache to 'fp'.
  513. *
  514. * Requires:
  515. * \li resolver to be valid.
  516. */
  517. ISC_LANG_ENDDECLS
  518. #endif /* DNS_RESOLVER_H */