4 * DNS Resolver definitions
6 * a Net::DNS like library for C
8 * (c) NLnet Labs, 2005-2006
10 * See the file LICENSE for the license
16 * Defines the ldns_resolver structure, a stub resolver that can send queries and parse answers.
20 #ifndef LDNS_RESOLVER_H
21 #define LDNS_RESOLVER_H
23 #include <ldns/error.h>
24 #include <ldns/common.h>
26 #include <ldns/tsig.h>
27 #include <ldns/rdata.h>
28 #include <ldns/packet.h>
35 /** Default location of the resolv.conf file */
36 #define LDNS_RESOLV_CONF "/etc/resolv.conf"
37 /** Default location of the hosts file */
38 #define LDNS_RESOLV_HOSTS "/etc/hosts"
40 #define LDNS_RESOLV_KEYWORD -1
41 #define LDNS_RESOLV_DEFDOMAIN 0
42 #define LDNS_RESOLV_NAMESERVER 1
43 #define LDNS_RESOLV_SEARCH 2
44 #define LDNS_RESOLV_SORTLIST 3
45 #define LDNS_RESOLV_OPTIONS 4
46 #define LDNS_RESOLV_ANCHOR 5
47 #define LDNS_RESOLV_KEYWORDS 6
49 #define LDNS_RESOLV_INETANY 0
50 #define LDNS_RESOLV_INET 1
51 #define LDNS_RESOLV_INET6 2
53 #define LDNS_RESOLV_RTT_INF 0 /* infinity */
54 #define LDNS_RESOLV_RTT_MIN 1 /* reachable */
57 * DNS stub resolver structure
59 struct ldns_struct_resolver
61 /** Port to send queries to */
64 /** Array of nameservers to query (IP addresses or dnames) */
65 ldns_rdf **_nameservers;
66 /** Number of nameservers in \c _nameservers */
67 size_t _nameserver_count; /* how many do we have */
69 /** Round trip time; 0 -> infinity. Unit: ms? */
72 /** Wether or not to be recursive */
75 /** Print debug information */
78 /** Default domain to add to non fully qualified domain names */
81 /** Searchlist array, add the names in this array if a query cannot be found */
82 ldns_rdf **_searchlist;
84 /** Number of entries in the searchlist array */
85 size_t _searchlist_count;
87 /** Number of times to retry before giving up */
89 /** Time to wait before retrying */
91 /** Use new fallback mechanism (try EDNS, then do TCP) */
94 /** Whether to do DNSSEC */
96 /** Whether to set the CD bit on DNSSEC requests */
98 /** Optional trust anchors for complete DNSSEC validation */
99 ldns_rr_list * _dnssec_anchors;
100 /** Whether to use tcp or udp (tcp if the value is true)*/
102 /** Whether to ignore the tc bit */
104 /** Whether to use ip6, 0->does not matter, 1 is IPv4, 2 is IPv6 */
106 /** If true append the default domain */
108 /** If true apply the search list */
110 /** Timeout for socket connections */
111 struct timeval _timeout;
112 /** Only try the first nameserver, and return with an error directly if it fails */
114 /** Randomly choose a nameserver */
116 /** Keep some things to make AXFR possible */
118 /** Count the number of LDNS_RR_TYPE_SOA RRs we have seen so far
119 * (the second one signifies the end of the AXFR)
122 /* when axfring we get complete packets from the server
123 but we want to give the caller 1 rr at a time, so
124 keep the current pkt */
125 /** Packet currently handled when doing part of an AXFR */
126 ldns_pkt *_cur_axfr_pkt;
127 /** Counter for within the AXFR packets */
129 /* EDNS0 available buffer size */
130 uint16_t _edns_udp_size;
132 /* Optional tsig key for signing queries,
133 outgoing messages are signed if and only if both are set
135 /** Name of the key to use with TSIG, if _tsig_keyname and _tsig_keydata both contain values, outgoing messages are automatically signed with TSIG. */
137 /** Secret key data to use with TSIG, if _tsig_keyname and _tsig_keydata both contain values, outgoing messages are automatically signed with TSIG. */
139 /** TSIG signing algorithm */
140 char *_tsig_algorithm;
142 typedef struct ldns_struct_resolver ldns_resolver;
145 /* read access functions */
148 * Get the port the resolver should use
149 * \param[in] r the resolver
150 * \return the port number
152 uint16_t ldns_resolver_port(const ldns_resolver *r);
155 * Is the resolver set to recurse
156 * \param[in] r the resolver
157 * \return true if so, otherwise false
159 bool ldns_resolver_recursive(const ldns_resolver *r);
162 * Get the debug status of the resolver
163 * \param[in] r the resolver
164 * \return true if so, otherwise false
166 bool ldns_resolver_debug(const ldns_resolver *r);
169 * Get the number of retries
170 * \param[in] r the resolver
171 * \return the number of retries
173 uint8_t ldns_resolver_retry(const ldns_resolver *r);
176 * Get the retransmit interval
177 * \param[in] r the resolver
178 * \return the retransmit interval
180 uint8_t ldns_resolver_retrans(const ldns_resolver *r);
183 * Get the truncation fallback status
184 * \param[in] r the resolver
185 * \return whether the truncation fallback mechanism is used
187 bool ldns_resolver_fallback(const ldns_resolver *r);
190 * Does the resolver use ip6 or ip4
191 * \param[in] r the resolver
192 * \return 0: both, 1: ip4, 2:ip6
194 uint8_t ldns_resolver_ip6(const ldns_resolver *r);
197 * Get the resolver's udp size
198 * \param[in] r the resolver
199 * \return the udp mesg size
201 uint16_t ldns_resolver_edns_udp_size(const ldns_resolver *r);
203 * Does the resolver use tcp or udp
204 * \param[in] r the resolver
205 * \return true: tcp, false: udp
207 bool ldns_resolver_usevc(const ldns_resolver *r);
209 * Does the resolver only try the first nameserver
210 * \param[in] r the resolver
211 * \return true: yes, fail, false: no, try the others
213 bool ldns_resolver_fail(const ldns_resolver *r);
215 * Does the resolver apply default domain name
216 * \param[in] r the resolver
217 * \return true: yes, false: no
219 bool ldns_resolver_defnames(const ldns_resolver *r);
221 * Does the resolver apply search list
222 * \param[in] r the resolver
223 * \return true: yes, false: no
225 bool ldns_resolver_dnsrch(const ldns_resolver *r);
227 * Does the resolver do DNSSEC
228 * \param[in] r the resolver
229 * \return true: yes, false: no
231 bool ldns_resolver_dnssec(const ldns_resolver *r);
233 * Does the resolver set the CD bit
234 * \param[in] r the resolver
235 * \return true: yes, false: no
237 bool ldns_resolver_dnssec_cd(const ldns_resolver *r);
239 * Get the resolver's DNSSEC anchors
240 * \param[in] r the resolver
241 * \return an rr_list containg trusted DNSSEC anchors
243 ldns_rr_list * ldns_resolver_dnssec_anchors(const ldns_resolver *r);
245 * Does the resolver ignore the TC bit (truncated)
246 * \param[in] r the resolver
247 * \return true: yes, false: no
249 bool ldns_resolver_igntc(const ldns_resolver *r);
251 * Does the resolver randomize the nameserver before usage
252 * \param[in] r the resolver
253 * \return true: yes, false: no
255 bool ldns_resolver_random(const ldns_resolver *r);
257 * How many nameserver are configured in the resolver
258 * \param[in] r the resolver
259 * \return number of nameservers
261 size_t ldns_resolver_nameserver_count(const ldns_resolver *r);
263 * What is the default dname to add to relative queries
264 * \param[in] r the resolver
265 * \return the dname which is added
267 ldns_rdf *ldns_resolver_domain(const ldns_resolver *r);
269 * What is the timeout on socket connections
270 * \param[in] r the resolver
271 * \return the timeout as struct timeval
273 struct timeval ldns_resolver_timeout(const ldns_resolver *r);
275 * What is the searchlist as used by the resolver
276 * \param[in] r the resolver
277 * \return a ldns_rdf pointer to a list of the addresses
279 ldns_rdf** ldns_resolver_searchlist(const ldns_resolver *r);
281 * Return the configured nameserver ip address
282 * \param[in] r the resolver
283 * \return a ldns_rdf pointer to a list of the addresses
285 ldns_rdf** ldns_resolver_nameservers(const ldns_resolver *r);
287 * Return the used round trip times for the nameservers
288 * \param[in] r the resolver
289 * \return a size_t* pointer to the list.
292 size_t * ldns_resolver_rtt(const ldns_resolver *r);
294 * Return the used round trip time for a specific nameserver
295 * \param[in] r the resolver
296 * \param[in] pos the index to the nameserver
297 * \return the rrt, 0: infinite, >0: undefined (as of * yet)
299 size_t ldns_resolver_nameserver_rtt(const ldns_resolver *r, size_t pos);
301 * Return the tsig keyname as used by the nameserver
302 * \param[in] r the resolver
303 * \return the name used.
305 char *ldns_resolver_tsig_keyname(const ldns_resolver *r);
307 * Return the tsig algorithm as used by the nameserver
308 * \param[in] r the resolver
309 * \return the algorithm used.
311 char *ldns_resolver_tsig_algorithm(const ldns_resolver *r);
313 * Return the tsig keydata as used by the nameserver
314 * \param[in] r the resolver
315 * \return the keydata used.
317 char *ldns_resolver_tsig_keydata(const ldns_resolver *r);
319 * pop the last nameserver from the resolver.
320 * \param[in] r the resolver
321 * \return the popped address or NULL if empty
323 ldns_rdf* ldns_resolver_pop_nameserver(ldns_resolver *r);
326 * Return the resolver's searchlist count
327 * \param[in] r the resolver
328 * \return the searchlist count
330 size_t ldns_resolver_searchlist_count(const ldns_resolver *r);
332 /* write access function */
334 * Set the port the resolver should use
335 * \param[in] r the resolver
336 * \param[in] p the port number
338 void ldns_resolver_set_port(ldns_resolver *r, uint16_t p);
341 * Set the resolver recursion
342 * \param[in] r the resolver
343 * \param[in] b true: set to recurse, false: unset
345 void ldns_resolver_set_recursive(ldns_resolver *r, bool b);
348 * Set the resolver debugging
349 * \param[in] r the resolver
350 * \param[in] b true: debug on: false debug off
352 void ldns_resolver_set_debug(ldns_resolver *r, bool b);
355 * Incremental the resolver's nameserver count.
356 * \param[in] r the resolver
358 void ldns_resolver_incr_nameserver_count(ldns_resolver *r);
361 * Decrement the resolver's nameserver count.
362 * \param[in] r the resolver
364 void ldns_resolver_dec_nameserver_count(ldns_resolver *r);
367 * Set the resolver's nameserver count directly.
368 * \param[in] r the resolver
369 * \param[in] c the nameserver count
371 void ldns_resolver_set_nameserver_count(ldns_resolver *r, size_t c);
374 * Set the resolver's nameserver count directly by using an rdf list
375 * \param[in] r the resolver
376 * \param[in] rd the resolver addresses
378 void ldns_resolver_set_nameservers(ldns_resolver *r, ldns_rdf **rd);
381 * Set the resolver's default domain. This gets appended when no
382 * absolute name is given
383 * \param[in] r the resolver
384 * \param[in] rd the name to append
386 void ldns_resolver_set_domain(ldns_resolver *r, ldns_rdf *rd);
389 * Set the resolver's socket time out when talking to remote hosts
390 * \param[in] r the resolver
391 * \param[in] timeout the timeout to use
393 void ldns_resolver_set_timeout(ldns_resolver *r, struct timeval timeout);
396 * Push a new rd to the resolver's searchlist
397 * \param[in] r the resolver
398 * \param[in] rd to push
400 void ldns_resolver_push_searchlist(ldns_resolver *r, ldns_rdf *rd);
403 * Whether the resolver uses the name set with _set_domain
404 * \param[in] r the resolver
405 * \param[in] b true: use the defaults, false: don't use them
407 void ldns_resolver_set_defnames(ldns_resolver *r, bool b);
410 * Whether the resolver uses a virtual circuit (TCP)
411 * \param[in] r the resolver
412 * \param[in] b true: use TCP, false: don't use TCP
414 void ldns_resolver_set_usevc(ldns_resolver *r, bool b);
417 * Whether the resolver uses the searchlist
418 * \param[in] r the resolver
419 * \param[in] b true: use the list, false: don't use the list
421 void ldns_resolver_set_dnsrch(ldns_resolver *r, bool b);
424 * Whether the resolver uses DNSSEC
425 * \param[in] r the resolver
426 * \param[in] b true: use DNSSEC, false: don't use DNSSEC
428 void ldns_resolver_set_dnssec(ldns_resolver *r, bool b);
431 * Whether the resolver uses the checking disable bit
432 * \param[in] r the resolver
433 * \param[in] b true: enable , false: don't use TCP
435 void ldns_resolver_set_dnssec_cd(ldns_resolver *r, bool b);
437 * Set the resolver's DNSSEC anchor list directly. RRs should be of type DS or DNSKEY.
438 * \param[in] r the resolver
439 * \param[in] l the list of RRs to use as trust anchors
441 void ldns_resolver_set_dnssec_anchors(ldns_resolver *r, ldns_rr_list * l);
444 * Push a new trust anchor to the resolver. It must be a DS or DNSKEY rr
445 * \param[in] r the resolver.
446 * \param[in] rr the RR to add as a trust anchor.
449 ldns_status ldns_resolver_push_dnssec_anchor(ldns_resolver *r, ldns_rr *rr);
452 * Set the resolver retrans timeout (in seconds)
453 * \param[in] r the resolver
454 * \param[in] re the retransmission interval in seconds
456 void ldns_resolver_set_retrans(ldns_resolver *r, uint8_t re);
459 * Set whether the resolvers truncation fallback mechanism is used
460 * when ldns_resolver_query() is called.
461 * \param[in] r the resolver
462 * \param[in] fallback whether to use the fallback mechanism
464 void ldns_resolver_set_fallback(ldns_resolver *r, bool fallback);
467 * Set the resolver retry interval (in seconds)
468 * \param[in] r the resolver
469 * \param[in] re the retry interval
471 void ldns_resolver_set_retry(ldns_resolver *r, uint8_t re);
474 * Whether the resolver uses ip6
475 * \param[in] r the resolver
476 * \param[in] i 0: no pref, 1: ip4, 2: ip6
478 void ldns_resolver_set_ip6(ldns_resolver *r, uint8_t i);
481 * Whether or not to fail after one failed query
482 * \param[in] r the resolver
483 * \param[in] b true: yes fail, false: continue with next nameserver
485 void ldns_resolver_set_fail(ldns_resolver *r, bool b);
488 * Whether or not to ignore the TC bit
489 * \param[in] r the resolver
490 * \param[in] b true: yes ignore, false: don't ignore
492 void ldns_resolver_set_igntc(ldns_resolver *r, bool b);
495 * Set maximum udp size
496 * \param[in] r the resolver
497 * \param[in] s the udp max size
499 void ldns_resolver_set_edns_udp_size(ldns_resolver *r, uint16_t s);
502 * Set the tsig key name
503 * \param[in] r the resolver
504 * \param[in] tsig_keyname the tsig key name
506 void ldns_resolver_set_tsig_keyname(ldns_resolver *r, char *tsig_keyname);
509 * Set the tsig algorithm
510 * \param[in] r the resolver
511 * \param[in] tsig_algorithm the tsig algorithm
513 void ldns_resolver_set_tsig_algorithm(ldns_resolver *r, char *tsig_algorithm);
516 * Set the tsig key data
517 * \param[in] r the resolver
518 * \param[in] tsig_keydata the key data
520 void ldns_resolver_set_tsig_keydata(ldns_resolver *r, char *tsig_keydata);
523 * Set round trip time for all nameservers. Note this currently
524 * differentiates between: unreachable and reachable.
525 * \param[in] r the resolver
526 * \param[in] rtt a list with the times
528 void ldns_resolver_set_rtt(ldns_resolver *r, size_t *rtt);
531 * Set round trip time for a specific nameserver. Note this
532 * currently differentiates between: unreachable and reachable.
533 * \param[in] r the resolver
534 * \param[in] pos the nameserver position
535 * \param[in] value the rtt
537 void ldns_resolver_set_nameserver_rtt(ldns_resolver *r, size_t pos, size_t value);
540 * Should the nameserver list be randomized before each use
541 * \param[in] r the resolver
542 * \param[in] b: true: randomize, false: don't
544 void ldns_resolver_set_random(ldns_resolver *r, bool b);
547 * Push a new nameserver to the resolver. It must be an IP
549 * \param[in] r the resolver
550 * \param[in] n the ip address
551 * \return ldns_status a status
553 ldns_status ldns_resolver_push_nameserver(ldns_resolver *r, ldns_rdf *n);
556 * Push a new nameserver to the resolver. It must be an
557 * A or AAAA RR record type
558 * \param[in] r the resolver
559 * \param[in] rr the resource record
560 * \return ldns_status a status
562 ldns_status ldns_resolver_push_nameserver_rr(ldns_resolver *r, ldns_rr *rr);
565 * Push a new nameserver rr_list to the resolver.
566 * \param[in] r the resolver
567 * \param[in] rrlist the rr_list to push
568 * \return ldns_status a status
570 ldns_status ldns_resolver_push_nameserver_rr_list(ldns_resolver *r, ldns_rr_list *rrlist);
573 * Send the query for using the resolver and take the search list into account
574 * The search algorithm is as follows:
575 * If the name is absolute, try it as-is, otherwise apply the search list
576 * \param[in] *r operate using this resolver
577 * \param[in] *rdf query for this name
578 * \param[in] t query for this type (may be 0, defaults to A)
579 * \param[in] c query for this class (may be 0, default to IN)
580 * \param[in] flags the query flags
582 * \return ldns_pkt* a packet with the reply from the nameserver
584 ldns_pkt* ldns_resolver_search(const ldns_resolver *r, const ldns_rdf *rdf, ldns_rr_type t, ldns_rr_class c, uint16_t flags);
587 * Form a query packet from a resolver and name/type/class combo
588 * \param[out] **q a pointer to a ldns_pkt pointer (initialized by this function)
589 * \param[in] *r operate using this resolver
590 * \param[in] *name query for this name
591 * \param[in] t query for this type (may be 0, defaults to A)
592 * \param[in] c query for this class (may be 0, default to IN)
593 * \param[in] f the query flags
595 * \return ldns_pkt* a packet with the reply from the nameserver
597 ldns_status ldns_resolver_prepare_query_pkt(ldns_pkt **q, ldns_resolver *r, const ldns_rdf *name, ldns_rr_type t, ldns_rr_class c, uint16_t f);
600 * Send the query for name as-is
601 * \param[out] **answer a pointer to a ldns_pkt pointer (initialized by this function)
602 * \param[in] *r operate using this resolver
603 * \param[in] *name query for this name
604 * \param[in] t query for this type (may be 0, defaults to A)
605 * \param[in] c query for this class (may be 0, default to IN)
606 * \param[in] flags the query flags
608 * \return ldns_pkt* a packet with the reply from the nameserver
610 ldns_status ldns_resolver_send(ldns_pkt **answer, ldns_resolver *r, const ldns_rdf *name, ldns_rr_type t, ldns_rr_class c, uint16_t flags);
613 * Send the given packet to a nameserver
614 * \param[out] **answer a pointer to a ldns_pkt pointer (initialized by this function)
615 * \param[in] *r operate using this resolver
616 * \param[in] *query_pkt query
618 ldns_status ldns_resolver_send_pkt(ldns_pkt **answer, ldns_resolver *r, ldns_pkt *query_pkt);
621 * Send a query to a nameserver
622 * \param[in] *r operate using this resolver
623 * \param[in] *name query for this name
624 * \param[in] *t query for this type (may be 0, defaults to A)
625 * \param[in] *c query for this class (may be 0, default to IN)
626 * \param[in] flags the query flags
628 * \return ldns_pkt* a packet with the reply from the nameserver
629 * if _defnames is true the default domain will be added
631 ldns_pkt* ldns_resolver_query(const ldns_resolver *r, const ldns_rdf *name, ldns_rr_type t, ldns_rr_class c, uint16_t flags);
635 * Create a new resolver structure
636 * \return ldns_resolver* pointer to new strcture
638 ldns_resolver* ldns_resolver_new(void);
641 * Create a resolver structure from a file like /etc/resolv.conf
642 * \param[out] r the new resolver
643 * \param[in] fp file pointer to create new resolver from
644 * if NULL use /etc/resolv.conf
645 * \return LDNS_STATUS_OK or the error
647 ldns_status ldns_resolver_new_frm_fp(ldns_resolver **r, FILE *fp);
650 * Create a resolver structure from a file like /etc/resolv.conf
651 * \param[out] r the new resolver
652 * \param[in] fp file pointer to create new resolver from
653 * if NULL use /etc/resolv.conf
654 * \param[in] line_nr pointer to an integer containing the current line number (for debugging purposes)
655 * \return LDNS_STATUS_OK or the error
657 ldns_status ldns_resolver_new_frm_fp_l(ldns_resolver **r, FILE *fp, int *line_nr);
660 * Configure a resolver by means of a resolv.conf file
661 * The file may be NULL in which case there will be
662 * looked the RESOLV_CONF (defaults to /etc/resolv.conf
663 * \param[out] r the new resolver
664 * \param[in] filename the filename to use
665 * \return LDNS_STATUS_OK or the error
667 ldns_status ldns_resolver_new_frm_file(ldns_resolver **r, const char *filename);
670 * Frees the allocated space for this resolver. Only frees the resolver pionter! You should probably be using _deep_free.
671 * \param res resolver to free
673 void ldns_resolver_free(ldns_resolver *res);
676 * Frees the allocated space for this resolver and all it's data
677 * \param res resolver to free
679 void ldns_resolver_deep_free(ldns_resolver *res);
682 * Get the next stream of RRs in a AXFR
683 * \param[in] resolver the resolver to use. First ldns_axfr_start() must be
685 * \return ldns_rr the next RR from the AXFR stream
686 * After you get this returned RR (not NULL: on error), then check if
687 * ldns_axfr_complete() is true to see if the zone transfer has completed.
689 ldns_rr* ldns_axfr_next(ldns_resolver *resolver);
692 * Returns true if the axfr transfer has completed (i.e. 2 SOA RRs and no errors were encountered
693 * \param[in] resolver the resolver that is used
694 * \return bool true if axfr transfer was completed without error
696 bool ldns_axfr_complete(const ldns_resolver *resolver);
699 * Returns a pointer to the last ldns_pkt that was sent by the server in the AXFR transfer
700 * uasable for instance to get the error code on failure
701 * \param[in] res the resolver that was used in the axfr transfer
702 * \return ldns_pkt the last packet sent
704 ldns_pkt *ldns_axfr_last_pkt(const ldns_resolver *res);
707 * Randomize the nameserver list in the resolver
708 * \param[in] r the resolver
710 void ldns_resolver_nameservers_randomize(ldns_resolver *r);
713 * Returns true if at least one of the provided keys is a trust anchor
714 * \param[in] r the current resolver
715 * \param[in] keys the keyset to check
716 * \param[out] trusted_keys the subset of trusted keys in the 'keys' rrset
717 * \return true if at least one of the provided keys is a configured trust anchor
719 bool ldns_resolver_trusted_key(const ldns_resolver *r, ldns_rr_list * keys, ldns_rr_list * trusted_keys);
725 #endif /* LDNS_RESOLVER_H */