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

   1 /*
   2  * Copyright (C) 2004, 2005, 2007, 2008  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-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
  18 /* $Id: dispatch.h,v 1.48.18.5.12.2 2008/07/23 07:28:56 tbox Exp $ */
  19
  20 #ifndef DNS_DISPATCH_H
  21 #define DNS_DISPATCH_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*! \file
  28  * \brief
  29  * DNS Dispatch Management
  30  *      Shared UDP and single-use TCP dispatches for queries and responses.
  31  *
  32  * MP:
  33  *
  34  *\li           All locking is performed internally to each dispatch.
  35  *      Restrictions apply to dns_dispatch_removeresponse().
  36  *
  37  * Reliability:
  38  *
  39  * Resources:
  40  *
  41  * Security:
  42  *
  43  *\li   Depends on the isc_socket_t and dns_message_t for prevention of
  44  *      buffer overruns.
  45  *
  46  * Standards:
  47  *
  48  *\li   None.
  49  */
  50
  51 /***
  52  *** Imports
  53  ***/
  54
  55 #include <isc/buffer.h>
  56 #include <isc/lang.h>
  57 #include <isc/socket.h>
  58 #include <dns/types.h>
  59
  60 #include <dns/types.h>
  61
  62 ISC_LANG_BEGINDECLS
  63
  64 /*%
  65  * This event is sent to a task when a response comes in.
  66  * No part of this structure should ever be modified by the caller,
  67  * other than parts of the buffer.  The holy parts of the buffer are
  68  * the base and size of the buffer.  All other parts of the buffer may
  69  * be used.  On event delivery the used region contains the packet.
  70  *
  71  * "id" is the received message id,
  72  *
  73  * "addr" is the host that sent it to us,
  74  *
  75  * "buffer" holds state on the received data.
  76  *
  77  * The "free" routine for this event will clean up itself as well as
  78  * any buffer space allocated from common pools.
  79  */
  80
  81 struct dns_dispatchevent {
  82         ISC_EVENT_COMMON(dns_dispatchevent_t);  /*%< standard event common */
  83         isc_result_t            result;         /*%< result code */
  84         isc_int32_t             id;             /*%< message id */
  85         isc_sockaddr_t          addr;           /*%< address recv'd from */
  86         struct in6_pktinfo      pktinfo;        /*%< reply info for v6 */
  87         isc_buffer_t            buffer;         /*%< data buffer */
  88         isc_uint32_t            attributes;     /*%< mirrored from socket.h */
  89 };
  90
  91 /*@{*/
  92 /*%
  93  * Attributes for added dispatchers.
  94  *
  95  * Values with the mask 0xffff0000 are application defined.
  96  * Values with the mask 0x0000ffff are library defined.
  97  *
  98  * Insane values (like setting both TCP and UDP) are not caught.  Don't
  99  * do that.
 100  *
 101  * _PRIVATE
 102  *      The dispatcher cannot be shared.
 103  *
 104  * _TCP, _UDP
 105  *      The dispatcher is a TCP or UDP socket.
 106  *
 107  * _IPV4, _IPV6
 108  *      The dispatcher uses an ipv4 or ipv6 socket.
 109  *
 110  * _NOLISTEN
 111  *      The dispatcher should not listen on the socket.
 112  *
 113  * _MAKEQUERY
 114  *      The dispatcher can be used to issue queries to other servers, and
 115  *      accept replies from them.
 116  *
 117  * _RANDOMPORT
 118  *      Allocate UDP port randomly.
 119  */
 120 #define DNS_DISPATCHATTR_PRIVATE        0x00000001U
 121 #define DNS_DISPATCHATTR_TCP            0x00000002U
 122 #define DNS_DISPATCHATTR_UDP            0x00000004U
 123 #define DNS_DISPATCHATTR_IPV4           0x00000008U
 124 #define DNS_DISPATCHATTR_IPV6           0x00000010U
 125 #define DNS_DISPATCHATTR_NOLISTEN       0x00000020U
 126 #define DNS_DISPATCHATTR_MAKEQUERY      0x00000040U
 127 #define DNS_DISPATCHATTR_CONNECTED      0x00000080U
 128 #define DNS_DISPATCHATTR_RANDOMPORT     0x00000100U
 129 /*@}*/
 130
 131 isc_result_t
 132 dns_dispatchmgr_create(isc_mem_t *mctx, isc_entropy_t *entropy,
 133                        dns_dispatchmgr_t **mgrp);
 134 /*%<
 135  * Creates a new dispatchmgr object.
 136  *
 137  * Requires:
 138  *\li   "mctx" be a valid memory context.
 139  *
 140  *\li   mgrp != NULL && *mgrp == NULL
 141  *
 142  *\li   "entropy" may be NULL, in which case an insecure random generator
 143  *      will be used.  If it is non-NULL, it must be a valid entropy
 144  *      source.
 145  *
 146  * Returns:
 147  *\li   ISC_R_SUCCESS   -- all ok
 148  *
 149  *\li   anything else   -- failure
 150  */
 151
 152
 153 void
 154 dns_dispatchmgr_destroy(dns_dispatchmgr_t **mgrp);
 155 /*%<
 156  * Destroys the dispatchmgr when it becomes empty.  This could be
 157  * immediately.
 158  *
 159  * Requires:
 160  *\li   mgrp != NULL && *mgrp is a valid dispatchmgr.
 161  */
 162
 163
 164 void
 165 dns_dispatchmgr_setblackhole(dns_dispatchmgr_t *mgr, dns_acl_t *blackhole);
 166 /*%<
 167  * Sets the dispatcher's "blackhole list," a list of addresses that will
 168  * be ignored by all dispatchers created by the dispatchmgr.
 169  *
 170  * Requires:
 171  * \li  mgrp is a valid dispatchmgr
 172  * \li  blackhole is a valid acl
 173  */
 174
 175
 176 dns_acl_t *
 177 dns_dispatchmgr_getblackhole(dns_dispatchmgr_t *mgr);
 178 /*%<
 179  * Gets a pointer to the dispatcher's current blackhole list,
 180  * without incrementing its reference count.
 181  *
 182  * Requires:
 183  *\li   mgr is a valid dispatchmgr
 184  * Returns:
 185  *\li   A pointer to the current blackhole list, or NULL.
 186  */
 187
 188 void
 189 dns_dispatchmgr_setblackportlist(dns_dispatchmgr_t *mgr,
 190                                  dns_portlist_t *portlist);
 191 /*%<
 192  * Sets a list of UDP ports that won't be used when creating a udp
 193  * dispatch with a wildcard port.
 194  *
 195  * Requires:
 196  *\li   mgr is a valid dispatchmgr
 197  *\li   portlist to be NULL or a valid port list.
 198  */
 199
 200 dns_portlist_t *
 201 dns_dispatchmgr_getblackportlist(dns_dispatchmgr_t *mgr);
 202 /*%<
 203  * Return the current port list.
 204  *
 205  * Requires:
 206  *\li   mgr is a valid dispatchmgr
 207  */
 208
 209
 210
 211 isc_result_t
 212 dns_dispatch_getudp(dns_dispatchmgr_t *mgr, isc_socketmgr_t *sockmgr,
 213                     isc_taskmgr_t *taskmgr, isc_sockaddr_t *localaddr,
 214                     unsigned int buffersize,
 215                     unsigned int maxbuffers, unsigned int maxrequests,
 216                     unsigned int buckets, unsigned int increment,
 217                     unsigned int attributes, unsigned int mask,
 218                     dns_dispatch_t **dispp);
 219 /*%<
 220  * Attach to existing dns_dispatch_t if one is found with dns_dispatchmgr_find,
 221  * otherwise create a new UDP dispatch.
 222  *
 223  * Requires:
 224  *\li   All pointer parameters be valid for their respective types.
 225  *
 226  *\li   dispp != NULL && *disp == NULL
 227  *
 228  *\li   512 <= buffersize <= 64k
 229  *
 230  *\li   maxbuffers > 0
 231  *
 232  *\li   buckets < 2097169
 233  *
 234  *\li   increment > buckets
 235  *
 236  *\li   (attributes & DNS_DISPATCHATTR_TCP) == 0
 237  *
 238  * Returns:
 239  *\li   ISC_R_SUCCESS   -- success.
 240  *
 241  *\li   Anything else   -- failure.
 242  */
 243
 244 isc_result_t
 245 dns_dispatch_createtcp(dns_dispatchmgr_t *mgr, isc_socket_t *sock,
 246                        isc_taskmgr_t *taskmgr, unsigned int buffersize,
 247                        unsigned int maxbuffers, unsigned int maxrequests,
 248                        unsigned int buckets, unsigned int increment,
 249                        unsigned int attributes, dns_dispatch_t **dispp);
 250 /*%<
 251  * Create a new dns_dispatch and attach it to the provided isc_socket_t.
 252  *
 253  * For all dispatches, "buffersize" is the maximum packet size we will
 254  * accept.
 255  *
 256  * "maxbuffers" and "maxrequests" control the number of buffers in the
 257  * overall system and the number of buffers which can be allocated to
 258  * requests.
 259  *
 260  * "buckets" is the number of buckets to use, and should be prime.
 261  *
 262  * "increment" is used in a collision avoidance function, and needs to be
 263  * a prime > buckets, and not 2.
 264  *
 265  * Requires:
 266  *
 267  *\li   mgr is a valid dispatch manager.
 268  *
 269  *\li   sock is a valid.
 270  *
 271  *\li   task is a valid task that can be used internally to this dispatcher.
 272  *
 273  * \li  512 <= buffersize <= 64k
 274  *
 275  *\li   maxbuffers > 0.
 276  *
 277  *\li   maxrequests <= maxbuffers.
 278  *
 279  *\li   buckets < 2097169 (the next prime after 65536 * 32)
 280  *
 281  *\li   increment > buckets (and prime).
 282  *
 283  *\li   attributes includes #DNS_DISPATCHATTR_TCP and does not include
 284  *      #DNS_DISPATCHATTR_UDP.
 285  *
 286  * Returns:
 287  *\li   ISC_R_SUCCESS   -- success.
 288  *
 289  *\li   Anything else   -- failure.
 290  */
 291
 292 void
 293 dns_dispatch_attach(dns_dispatch_t *disp, dns_dispatch_t **dispp);
 294 /*%<
 295  * Attach to a dispatch handle.
 296  *
 297  * Requires:
 298  *\li   disp is valid.
 299  *
 300  *\li   dispp != NULL && *dispp == NULL
 301  */
 302
 303 void
 304 dns_dispatch_detach(dns_dispatch_t **dispp);
 305 /*%<
 306  * Detaches from the dispatch.
 307  *
 308  * Requires:
 309  *\li   dispp != NULL and *dispp be a valid dispatch.
 310  */
 311
 312 void
 313 dns_dispatch_starttcp(dns_dispatch_t *disp);
 314 /*%<
 315  * Start processing of a TCP dispatch once the socket connects.
 316  *
 317  * Requires:
 318  *\li   'disp' is valid.
 319  */
 320
 321 isc_result_t
 322 dns_dispatch_addresponse(dns_dispatch_t *disp, isc_sockaddr_t *dest,
 323                          isc_task_t *task, isc_taskaction_t action, void *arg,
 324                          isc_uint16_t *idp, dns_dispentry_t **resp);
 325 /*%<
 326  * Add a response entry for this dispatch.
 327  *
 328  * "*idp" is filled in with the assigned message ID, and *resp is filled in
 329  * to contain the magic token used to request event flow stop.
 330  *
 331  * Arranges for the given task to get a callback for response packets.  When
 332  * the event is delivered, it must be returned using dns_dispatch_freeevent()
 333  * or through dns_dispatch_removeresponse() for another to be delivered.
 334  *
 335  * Requires:
 336  *\li   "idp" be non-NULL.
 337  *
 338  *\li   "task" "action" and "arg" be set as appropriate.
 339  *
 340  *\li   "dest" be non-NULL and valid.
 341  *
 342  *\li   "resp" be non-NULL and *resp be NULL
 343  *
 344  * Ensures:
 345  *
 346  *\li   &lt;id, dest> is a unique tuple.  That means incoming messages
 347  *      are identifiable.
 348  *
 349  * Returns:
 350  *
 351  *\li   ISC_R_SUCCESS           -- all is well.
 352  *\li   ISC_R_NOMEMORY          -- memory could not be allocated.
 353  *\li   ISC_R_NOMORE            -- no more message ids can be allocated
 354  *                                 for this destination.
 355  */
 356
 357
 358 void
 359 dns_dispatch_removeresponse(dns_dispentry_t **resp,
 360                             dns_dispatchevent_t **sockevent);
 361 /*%<
 362  * Stops the flow of responses for the provided id and destination.
 363  * If "sockevent" is non-NULL, the dispatch event and associated buffer is
 364  * also returned to the system.
 365  *
 366  * Requires:
 367  *\li   "resp" != NULL and "*resp" contain a value previously allocated
 368  *      by dns_dispatch_addresponse();
 369  *
 370  *\li   May only be called from within the task given as the 'task'
 371  *      argument to dns_dispatch_addresponse() when allocating '*resp'.
 372  */
 373
 374
 375 isc_socket_t *
 376 dns_dispatch_getsocket(dns_dispatch_t *disp);
 377 /*%<
 378  * Return the socket associated with this dispatcher.
 379  *
 380  * Requires:
 381  *\li   disp is valid.
 382  *
 383  * Returns:
 384  *\li   The socket the dispatcher is using.
 385  */
 386
 387 isc_result_t
 388 dns_dispatch_getlocaladdress(dns_dispatch_t *disp, isc_sockaddr_t *addrp);
 389 /*%<
 390  * Return the local address for this dispatch.
 391  * This currently only works for dispatches using UDP sockets.
 392  *
 393  * Requires:
 394  *\li   disp is valid.
 395  *\li   addrp to be non null.
 396  *
 397  * Returns:
 398  *\li   ISC_R_SUCCESS
 399  *\li   ISC_R_NOTIMPLEMENTED
 400  */
 401
 402 void
 403 dns_dispatch_cancel(dns_dispatch_t *disp);
 404 /*%<
 405  * cancel outstanding clients
 406  *
 407  * Requires:
 408  *\li   disp is valid.
 409  */
 410
 411 void
 412 dns_dispatch_changeattributes(dns_dispatch_t *disp,
 413                               unsigned int attributes, unsigned int mask);
 414 /*%<
 415  * Set the bits described by "mask" to the corresponding values in
 416  * "attributes".
 417  *
 418  * That is:
 419  *
 420  * \code
 421  *      new = (old & ~mask) | (attributes & mask)
 422  * \endcode
 423  *
 424  * This function has a side effect when #DNS_DISPATCHATTR_NOLISTEN changes.
 425  * When the flag becomes off, the dispatch will start receiving on the
 426  * corresponding socket.  When the flag becomes on, receive events on the
 427  * corresponding socket will be canceled.
 428  *
 429  * Requires:
 430  *\li   disp is valid.
 431  *
 432  *\li   attributes are reasonable for the dispatch.  That is, setting the UDP
 433  *      attribute on a TCP socket isn't reasonable.
 434  */
 435
 436 void
 437 dns_dispatch_importrecv(dns_dispatch_t *disp, isc_event_t *event);
 438 /*%<
 439  * Inform the dispatcher of a socket receive.  This is used for sockets
 440  * shared between dispatchers and clients.  If the dispatcher fails to copy
 441  * or send the event, nothing happens.
 442  *
 443  * Requires:
 444  *\li   disp is valid, and the attribute DNS_DISPATCHATTR_NOLISTEN is set.
 445  *      event != NULL
 446  */
 447
 448 ISC_LANG_ENDDECLS
 449
 450 #endif /* DNS_DISPATCH_H */