home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / dns / resolver.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-09-17  |  12.1 KB  |  480 lines
  1. /*
  2.  * Copyright (C) 2004-2006  Internet Systems Consortium, Inc. ("ISC")
  3.  * Copyright (C) 1999-2001, 2003  Internet Software Consortium.
  4.  *
  5.  * Permission to use, copy, modify, and 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.  
  18. /* $Id: resolver.h,v 1.40.18.11 2006/02/01 22:39:17 marka Exp $ */
  19.  
  20. #ifndef DNS_RESOLVER_H
  21. #define DNS_RESOLVER_H 1
  22.  
  23. /*****
  24.  ***** Module Info
  25.  *****/
  26.  
  27. /*! \file
  28.  *
  29.  * \brief
  30.  * This is the BIND 9 resolver, the module responsible for resolving DNS
  31.  * requests by iteratively querying authoritative servers and following
  32.  * referrals.  This is a "full resolver", not to be confused with
  33.  * the stub resolvers most people associate with the word "resolver".
  34.  * The full resolver is part of the caching name server or resolver
  35.  * daemon the stub resolver talks to.
  36.  *
  37.  * MP:
  38.  *\li    The module ensures appropriate synchronization of data structures it
  39.  *    creates and manipulates.
  40.  *
  41.  * Reliability:
  42.  *\li    No anticipated impact.
  43.  *
  44.  * Resources:
  45.  *\li    TBS
  46.  *
  47.  * Security:
  48.  *\li    No anticipated impact.
  49.  *
  50.  * Standards:
  51.  *\li    RFCs:    1034, 1035, 2181, TBS
  52.  *\li    Drafts:    TBS
  53.  */
  54.  
  55. #include <isc/lang.h>
  56. #include <isc/socket.h>
  57.  
  58. #include <dns/types.h>
  59. #include <dns/fixedname.h>
  60.  
  61. ISC_LANG_BEGINDECLS
  62.  
  63. /*%
  64.  * A dns_fetchevent_t is sent when a 'fetch' completes.  Any of 'db',
  65.  * 'node', 'rdataset', and 'sigrdataset' may be bound.  It is the
  66.  * receiver's responsibility to detach before freeing the event.
  67.  * \brief
  68.  * 'rdataset', 'sigrdataset', 'client' and 'id' are the values that were
  69.  * supplied when dns_resolver_createfetch() was called.  They are returned
  70.  *  to the caller so that they may be freed.
  71.  */
  72. typedef struct dns_fetchevent {
  73.     ISC_EVENT_COMMON(struct dns_fetchevent);
  74.     dns_fetch_t *            fetch;
  75.     isc_result_t            result;
  76.     dns_rdatatype_t            qtype;
  77.     dns_db_t *            db;
  78.     dns_dbnode_t *            node;
  79.     dns_rdataset_t *        rdataset;
  80.     dns_rdataset_t *        sigrdataset;
  81.     dns_fixedname_t            foundname;
  82.     isc_sockaddr_t *        client;
  83.     dns_messageid_t            id;
  84. } dns_fetchevent_t;
  85.  
  86. /*
  87.  * Options that modify how a 'fetch' is done.
  88.  */
  89. #define DNS_FETCHOPT_TCP        0x01         /*%< Use TCP. */
  90. #define DNS_FETCHOPT_UNSHARED        0x02         /*%< See below. */
  91. #define DNS_FETCHOPT_RECURSIVE        0x04         /*%< Set RD? */
  92. #define DNS_FETCHOPT_NOEDNS0        0x08         /*%< Do not use EDNS. */
  93. #define DNS_FETCHOPT_FORWARDONLY    0x10         /*%< Only use forwarders. */
  94. #define DNS_FETCHOPT_NOVALIDATE        0x20         /*%< Disable validation. */
  95. #define DNS_FETCHOPT_EDNS512        0x40         /*%< Advertise a 512 byte
  96.                                   UDP buffer. */
  97.  
  98. #define    DNS_FETCHOPT_EDNSVERSIONSET    0x00800000
  99. #define    DNS_FETCHOPT_EDNSVERSIONMASK    0xff000000
  100. #define    DNS_FETCHOPT_EDNSVERSIONSHIFT    24
  101.  
  102. /*
  103.  * XXXRTH  Should this API be made semi-private?  (I.e.
  104.  * _dns_resolver_create()).
  105.  */
  106.  
  107. #define DNS_RESOLVER_CHECKNAMES        0x01
  108. #define DNS_RESOLVER_CHECKNAMESFAIL    0x02
  109.  
  110. isc_result_t
  111. dns_resolver_create(dns_view_t *view,
  112.             isc_taskmgr_t *taskmgr, unsigned int ntasks,
  113.             isc_socketmgr_t *socketmgr,
  114.             isc_timermgr_t *timermgr,
  115.             unsigned int options,
  116.             dns_dispatchmgr_t *dispatchmgr,
  117.             dns_dispatch_t *dispatchv4,
  118.             dns_dispatch_t *dispatchv6,
  119.             dns_resolver_t **resp);
  120.  
  121. /*%<
  122.  * Create a resolver.
  123.  *
  124.  * Notes:
  125.  *
  126.  *\li    Generally, applications should not create a resolver directly, but
  127.  *    should instead call dns_view_createresolver().
  128.  *
  129.  *\li    No options are currently defined.
  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.  
  156. void
  157. dns_resolver_freeze(dns_resolver_t *res);
  158. /*%<
  159.  * Freeze resolver.
  160.  *
  161.  * Notes:
  162.  *
  163.  *\li    Certain configuration changes cannot be made after the resolver
  164.  *    is frozen.  Fetches cannot be created until the resolver is frozen.
  165.  *
  166.  * Requires:
  167.  *
  168.  *\li    'res' is a valid, unfrozen resolver.
  169.  *
  170.  * Ensures:
  171.  *
  172.  *\li    'res' is frozen.
  173.  */
  174.  
  175. void
  176. dns_resolver_prime(dns_resolver_t *res);
  177. /*%<
  178.  * Prime resolver.
  179.  *
  180.  * Notes:
  181.  *
  182.  *\li    Resolvers which have a forwarding policy other than dns_fwdpolicy_only
  183.  *    need to be primed with the root nameservers, otherwise the root
  184.  *    nameserver hints data may be used indefinitely.  This function requests
  185.  *    that the resolver start a priming fetch, if it isn't already priming.
  186.  *
  187.  * Requires:
  188.  *
  189.  *\li    'res' is a valid, frozen resolver.
  190.  */
  191.  
  192.  
  193. void
  194. dns_resolver_whenshutdown(dns_resolver_t *res, isc_task_t *task,
  195.               isc_event_t **eventp);
  196. /*%<
  197.  * Send '*eventp' to 'task' when 'res' has completed shutdown.
  198.  *
  199.  * Notes:
  200.  *
  201.  *\li    It is not safe to detach the last reference to 'res' until
  202.  *    shutdown is complete.
  203.  *
  204.  * Requires:
  205.  *
  206.  *\li    'res' is a valid resolver.
  207.  *
  208.  *\li    'task' is a valid task.
  209.  *
  210.  *\li    *eventp is a valid event.
  211.  *
  212.  * Ensures:
  213.  *
  214.  *\li    *eventp == NULL.
  215.  */
  216.  
  217. void
  218. dns_resolver_shutdown(dns_resolver_t *res);
  219. /*%<
  220.  * Start the shutdown process for 'res'.
  221.  *
  222.  * Notes:
  223.  *
  224.  *\li    This call has no effect if the resolver is already shutting down.
  225.  *
  226.  * Requires:
  227.  *
  228.  *\li    'res' is a valid resolver.
  229.  */
  230.  
  231. void
  232. dns_resolver_attach(dns_resolver_t *source, dns_resolver_t **targetp);
  233.  
  234. void
  235. dns_resolver_detach(dns_resolver_t **resp);
  236.  
  237. isc_result_t
  238. dns_resolver_createfetch(dns_resolver_t *res, dns_name_t *name,
  239.              dns_rdatatype_t type,
  240.              dns_name_t *domain, dns_rdataset_t *nameservers,
  241.              dns_forwarders_t *forwarders,
  242.              unsigned int options, isc_task_t *task,
  243.              isc_taskaction_t action, void *arg,
  244.              dns_rdataset_t *rdataset,
  245.              dns_rdataset_t *sigrdataset,
  246.              dns_fetch_t **fetchp);
  247.  
  248. isc_result_t
  249. dns_resolver_createfetch2(dns_resolver_t *res, dns_name_t *name,
  250.               dns_rdatatype_t type,
  251.               dns_name_t *domain, dns_rdataset_t *nameservers,
  252.               dns_forwarders_t *forwarders,
  253.               isc_sockaddr_t *client, isc_uint16_t id,
  254.               unsigned int options, isc_task_t *task,
  255.               isc_taskaction_t action, void *arg,
  256.               dns_rdataset_t *rdataset,
  257.               dns_rdataset_t *sigrdataset,
  258.               dns_fetch_t **fetchp);
  259. /*%<
  260.  * Recurse to answer a question.
  261.  *
  262.  * Notes:
  263.  *
  264.  *\li    This call starts a query for 'name', type 'type'.
  265.  *
  266.  *\li    The 'domain' is a parent domain of 'name' for which
  267.  *    a set of name servers 'nameservers' is known.  If no
  268.  *    such name server information is available, set
  269.  *     'domain' and 'nameservers' to NULL.
  270.  *
  271.  *\li    'forwarders' is unimplemented, and subject to change when
  272.  *    we figure out how selective forwarding will work.
  273.  *
  274.  *\li    When the fetch completes (successfully or otherwise), a
  275.  *    #DNS_EVENT_FETCHDONE event with action 'action' and arg 'arg' will be
  276.  *    posted to 'task'.
  277.  *
  278.  *\li    The values of 'rdataset' and 'sigrdataset' will be returned in
  279.  *    the FETCHDONE event.
  280.  *
  281.  *\li    'client' and 'id' are used for duplicate query detection.  '*client'
  282.  *    must remain stable until after 'action' has been called or
  283.  *    dns_resolver_cancelfetch() is called.
  284.  *
  285.  * Requires:
  286.  *
  287.  *\li    'res' is a valid resolver that has been frozen.
  288.  *
  289.  *\li    'name' is a valid name.
  290.  *
  291.  *\li    'type' is not a meta type other than ANY.
  292.  *
  293.  *\li    'domain' is a valid name or NULL.
  294.  *
  295.  *\li    'nameservers' is a valid NS rdataset (whose owner name is 'domain')
  296.  *    iff. 'domain' is not NULL.
  297.  *
  298.  *\li    'forwarders' is NULL.
  299.  *
  300.  *\li    'client' is a valid sockaddr or NULL.
  301.  *
  302.  *\li    'options' contains valid options.
  303.  *
  304.  *\li    'rdataset' is a valid, disassociated rdataset.
  305.  *
  306.  *\li    'sigrdataset' is NULL, or is a valid, disassociated rdataset.
  307.  *
  308.  *\li    fetchp != NULL && *fetchp == NULL.
  309.  *
  310.  * Returns:
  311.  *
  312.  *\li    #ISC_R_SUCCESS                    Success
  313.  *\li    #DNS_R_DUPLICATE
  314.  *\li    #DNS_R_DROP
  315.  *
  316.  *\li    Many other values are possible, all of which indicate failure.
  317.  */
  318.  
  319. void
  320. dns_resolver_cancelfetch(dns_fetch_t *fetch);
  321. /*%<
  322.  * Cancel 'fetch'.
  323.  *
  324.  * Notes:
  325.  *
  326.  *\li    If 'fetch' has not completed, post its FETCHDONE event with a
  327.  *    result code of #ISC_R_CANCELED.
  328.  *
  329.  * Requires:
  330.  *
  331.  *\li    'fetch' is a valid fetch.
  332.  */
  333.  
  334. void
  335. dns_resolver_destroyfetch(dns_fetch_t **fetchp);
  336. /*%<
  337.  * Destroy 'fetch'.
  338.  *
  339.  * Requires:
  340.  *
  341.  *\li    '*fetchp' is a valid fetch.
  342.  *
  343.  *\li    The caller has received the FETCHDONE event (either because the
  344.  *    fetch completed or because dns_resolver_cancelfetch() was called).
  345.  *
  346.  * Ensures:
  347.  *
  348.  *\li    *fetchp == NULL.
  349.  */
  350.  
  351. dns_dispatchmgr_t *
  352. dns_resolver_dispatchmgr(dns_resolver_t *resolver);
  353.  
  354. dns_dispatch_t *
  355. dns_resolver_dispatchv4(dns_resolver_t *resolver);
  356.  
  357. dns_dispatch_t *
  358. dns_resolver_dispatchv6(dns_resolver_t *resolver);
  359.  
  360. isc_socketmgr_t *
  361. dns_resolver_socketmgr(dns_resolver_t *resolver);
  362.  
  363. isc_taskmgr_t *
  364. dns_resolver_taskmgr(dns_resolver_t *resolver);
  365.  
  366. isc_uint32_t
  367. dns_resolver_getlamettl(dns_resolver_t *resolver);
  368. /*%<
  369.  * Get the resolver's lame-ttl.  zero => no lame processing.
  370.  *
  371.  * Requires:
  372.  *\li    'resolver' to be valid.
  373.  */
  374.  
  375. void
  376. dns_resolver_setlamettl(dns_resolver_t *resolver, isc_uint32_t lame_ttl);
  377. /*%<
  378.  * Set the resolver's lame-ttl.  zero => no lame processing.
  379.  *
  380.  * Requires:
  381.  *\li    'resolver' to be valid.
  382.  */
  383.  
  384. unsigned int
  385. dns_resolver_nrunning(dns_resolver_t *resolver);
  386. /*%<
  387.  * Return the number of currently running resolutions in this
  388.  * resolver.  This is may be less than the number of outstanding
  389.  * fetches due to multiple identical fetches, or more than the
  390.  * number of of outstanding fetches due to the fact that resolution
  391.  * can continue even though a fetch has been canceled.
  392.  */
  393.  
  394. isc_result_t
  395. dns_resolver_addalternate(dns_resolver_t *resolver, isc_sockaddr_t *alt,
  396.               dns_name_t *name, in_port_t port);
  397. /*%<
  398.  * Add alternate addresses to be tried in the event that the nameservers
  399.  * for a zone are not available in the address families supported by the
  400.  * operating system.
  401.  *
  402.  * Require:
  403.  * \li    only one of 'name' or 'alt' to be valid.
  404.  */
  405.  
  406. void
  407. dns_resolver_setudpsize(dns_resolver_t *resolver, isc_uint16_t udpsize);
  408. /*%<
  409.  * Set the EDNS UDP buffer size advertised by the server.
  410.  */
  411.  
  412. isc_uint16_t
  413. dns_resolver_getudpsize(dns_resolver_t *resolver);
  414. /*%<
  415.  * Get the current EDNS UDP buffer size.
  416.  */
  417.  
  418. void
  419. dns_resolver_reset_algorithms(dns_resolver_t *resolver);
  420. /*%<
  421.  * Clear the disabled DNSSEC algorithms.
  422.  */
  423.  
  424. isc_result_t
  425. dns_resolver_disable_algorithm(dns_resolver_t *resolver, dns_name_t *name,
  426.                    unsigned int alg);
  427. /*%<
  428.  * Mark the give DNSSEC algorithm as disabled and below 'name'.
  429.  * Valid algorithms are less than 256.
  430.  *
  431.  * Returns:
  432.  *\li    #ISC_R_SUCCESS
  433.  *\li    #ISC_R_RANGE
  434.  *\li    #ISC_R_NOMEMORY
  435.  */
  436.  
  437. isc_boolean_t
  438. dns_resolver_algorithm_supported(dns_resolver_t *resolver, dns_name_t *name,
  439.                  unsigned int alg);
  440. /*%<
  441.  * Check if the given algorithm is supported by this resolver.
  442.  * This checks if the algorithm has been disabled via
  443.  * dns_resolver_disable_algorithm() then the underlying
  444.  * crypto libraries if not specifically disabled.
  445.  */
  446.  
  447. isc_boolean_t
  448. dns_resolver_digest_supported(dns_resolver_t *resolver, unsigned int digest_type);
  449. /*%<
  450.  * Is this digest type supported.
  451.  */
  452.  
  453. void
  454. dns_resolver_resetmustbesecure(dns_resolver_t *resolver);
  455.  
  456. isc_result_t
  457. dns_resolver_setmustbesecure(dns_resolver_t *resolver, dns_name_t *name,
  458.                  isc_boolean_t value);
  459.  
  460. isc_boolean_t
  461. dns_resolver_getmustbesecure(dns_resolver_t *resolver, dns_name_t *name);
  462.  
  463. void
  464. dns_resolver_setclientsperquery(dns_resolver_t *resolver,
  465.                 isc_uint32_t min, isc_uint32_t max);
  466.  
  467. void
  468. dns_resolver_getclientsperquery(dns_resolver_t *resolver, isc_uint32_t *cur,
  469.                 isc_uint32_t *min, isc_uint32_t *max);
  470.  
  471. isc_boolean_t
  472. dns_resolver_getzeronosoattl(dns_resolver_t *resolver);
  473.  
  474. void
  475. dns_resolver_setzeronosoattl(dns_resolver_t *resolver, isc_boolean_t state);
  476.  
  477. ISC_LANG_ENDDECLS
  478.  
  479. #endif /* DNS_RESOLVER_H */
  480.