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

   1 /*
   2  * Copyright (C) 2004, 2005, 2007  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 2007/08/28 07:20:05 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 #define DNS_DISPATCHATTR_PRIVATE        0x00000001U
 118 #define DNS_DISPATCHATTR_TCP            0x00000002U
 119 #define DNS_DISPATCHATTR_UDP            0x00000004U
 120 #define DNS_DISPATCHATTR_IPV4           0x00000008U
 121 #define DNS_DISPATCHATTR_IPV6           0x00000010U
 122 #define DNS_DISPATCHATTR_NOLISTEN       0x00000020U
 123 #define DNS_DISPATCHATTR_MAKEQUERY      0x00000040U
 124 #define DNS_DISPATCHATTR_CONNECTED      0x00000080U
 125 /*@}*/
 126
 127 isc_result_t
 128 dns_dispatchmgr_create(isc_mem_t *mctx, isc_entropy_t *entropy,
 129                        dns_dispatchmgr_t **mgrp);
 130 /*%<
 131  * Creates a new dispatchmgr object.
 132  *
 133  * Requires:
 134  *\li   "mctx" be a valid memory context.
 135  *
 136  *\li   mgrp != NULL && *mgrp == NULL
 137  *
 138  *\li   "entropy" may be NULL, in which case an insecure random generator
 139  *      will be used.  If it is non-NULL, it must be a valid entropy
 140  *      source.
 141  *
 142  * Returns:
 143  *\li   ISC_R_SUCCESS   -- all ok
 144  *
 145  *\li   anything else   -- failure
 146  */
 147
 148
 149 void
 150 dns_dispatchmgr_destroy(dns_dispatchmgr_t **mgrp);
 151 /*%<
 152  * Destroys the dispatchmgr when it becomes empty.  This could be
 153  * immediately.
 154  *
 155  * Requires:
 156  *\li   mgrp != NULL && *mgrp is a valid dispatchmgr.
 157  */
 158
 159
 160 void
 161 dns_dispatchmgr_setblackhole(dns_dispatchmgr_t *mgr, dns_acl_t *blackhole);
 162 /*%<
 163  * Sets the dispatcher's "blackhole list," a list of addresses that will
 164  * be ignored by all dispatchers created by the dispatchmgr.
 165  *
 166  * Requires:
 167  * \li  mgrp is a valid dispatchmgr
 168  * \li  blackhole is a valid acl
 169  */
 170
 171
 172 dns_acl_t *
 173 dns_dispatchmgr_getblackhole(dns_dispatchmgr_t *mgr);
 174 /*%<
 175  * Gets a pointer to the dispatcher's current blackhole list,
 176  * without incrementing its reference count.
 177  *
 178  * Requires:
 179  *\li   mgr is a valid dispatchmgr
 180  * Returns:
 181  *\li   A pointer to the current blackhole list, or NULL.
 182  */
 183
 184 void
 185 dns_dispatchmgr_setblackportlist(dns_dispatchmgr_t *mgr,
 186                                  dns_portlist_t *portlist);
 187 /*%<
 188  * Sets a list of UDP ports that won't be used when creating a udp
 189  * dispatch with a wildcard port.
 190  *
 191  * Requires:
 192  *\li   mgr is a valid dispatchmgr
 193  *\li   portlist to be NULL or a valid port list.
 194  */
 195
 196 dns_portlist_t *
 197 dns_dispatchmgr_getblackportlist(dns_dispatchmgr_t *mgr);
 198 /*%<
 199  * Return the current port list.
 200  *
 201  * Requires:
 202  *\li   mgr is a valid dispatchmgr
 203  */
 204
 205
 206
 207 isc_result_t
 208 dns_dispatch_getudp(dns_dispatchmgr_t *mgr, isc_socketmgr_t *sockmgr,
 209                     isc_taskmgr_t *taskmgr, isc_sockaddr_t *localaddr,
 210                     unsigned int buffersize,
 211                     unsigned int maxbuffers, unsigned int maxrequests,
 212                     unsigned int buckets, unsigned int increment,
 213                     unsigned int attributes, unsigned int mask,
 214                     dns_dispatch_t **dispp);
 215 /*%<
 216  * Attach to existing dns_dispatch_t if one is found with dns_dispatchmgr_find,
 217  * otherwise create a new UDP dispatch.
 218  *
 219  * Requires:
 220  *\li   All pointer parameters be valid for their respective types.
 221  *
 222  *\li   dispp != NULL && *disp == NULL
 223  *
 224  *\li   512 <= buffersize <= 64k
 225  *
 226  *\li   maxbuffers > 0
 227  *
 228  *\li   buckets < 2097169
 229  *
 230  *\li   increment > buckets
 231  *
 232  *\li   (attributes & DNS_DISPATCHATTR_TCP) == 0
 233  *
 234  * Returns:
 235  *\li   ISC_R_SUCCESS   -- success.
 236  *
 237  *\li   Anything else   -- failure.
 238  */
 239
 240 isc_result_t
 241 dns_dispatch_createtcp(dns_dispatchmgr_t *mgr, isc_socket_t *sock,
 242                        isc_taskmgr_t *taskmgr, unsigned int buffersize,
 243                        unsigned int maxbuffers, unsigned int maxrequests,
 244                        unsigned int buckets, unsigned int increment,
 245                        unsigned int attributes, dns_dispatch_t **dispp);
 246 /*%<
 247  * Create a new dns_dispatch and attach it to the provided isc_socket_t.
 248  *
 249  * For all dispatches, "buffersize" is the maximum packet size we will
 250  * accept.
 251  *
 252  * "maxbuffers" and "maxrequests" control the number of buffers in the
 253  * overall system and the number of buffers which can be allocated to
 254  * requests.
 255  *
 256  * "buckets" is the number of buckets to use, and should be prime.
 257  *
 258  * "increment" is used in a collision avoidance function, and needs to be
 259  * a prime > buckets, and not 2.
 260  *
 261  * Requires:
 262  *
 263  *\li   mgr is a valid dispatch manager.
 264  *
 265  *\li   sock is a valid.
 266  *
 267  *\li   task is a valid task that can be used internally to this dispatcher.
 268  *
 269  * \li  512 <= buffersize <= 64k
 270  *
 271  *\li   maxbuffers > 0.
 272  *
 273  *\li   maxrequests <= maxbuffers.
 274  *
 275  *\li   buckets < 2097169 (the next prime after 65536 * 32)
 276  *
 277  *\li   increment > buckets (and prime).
 278  *
 279  *\li   attributes includes #DNS_DISPATCHATTR_TCP and does not include
 280  *      #DNS_DISPATCHATTR_UDP.
 281  *
 282  * Returns:
 283  *\li   ISC_R_SUCCESS   -- success.
 284  *
 285  *\li   Anything else   -- failure.
 286  */
 287
 288 void
 289 dns_dispatch_attach(dns_dispatch_t *disp, dns_dispatch_t **dispp);
 290 /*%<
 291  * Attach to a dispatch handle.
 292  *
 293  * Requires:
 294  *\li   disp is valid.
 295  *
 296  *\li   dispp != NULL && *dispp == NULL
 297  */
 298
 299 void
 300 dns_dispatch_detach(dns_dispatch_t **dispp);
 301 /*%<
 302  * Detaches from the dispatch.
 303  *
 304  * Requires:
 305  *\li   dispp != NULL and *dispp be a valid dispatch.
 306  */
 307
 308 void
 309 dns_dispatch_starttcp(dns_dispatch_t *disp);
 310 /*%<
 311  * Start processing of a TCP dispatch once the socket connects.
 312  *
 313  * Requires:
 314  *\li   'disp' is valid.
 315  */
 316
 317 isc_result_t
 318 dns_dispatch_addresponse(dns_dispatch_t *disp, isc_sockaddr_t *dest,
 319                          isc_task_t *task, isc_taskaction_t action, void *arg,
 320                          isc_uint16_t *idp, dns_dispentry_t **resp);
 321 /*%<
 322  * Add a response entry for this dispatch.
 323  *
 324  * "*idp" is filled in with the assigned message ID, and *resp is filled in
 325  * to contain the magic token used to request event flow stop.
 326  *
 327  * Arranges for the given task to get a callback for response packets.  When
 328  * the event is delivered, it must be returned using dns_dispatch_freeevent()
 329  * or through dns_dispatch_removeresponse() for another to be delivered.
 330  *
 331  * Requires:
 332  *\li   "idp" be non-NULL.
 333  *
 334  *\li   "task" "action" and "arg" be set as appropriate.
 335  *
 336  *\li   "dest" be non-NULL and valid.
 337  *
 338  *\li   "resp" be non-NULL and *resp be NULL
 339  *
 340  * Ensures:
 341  *
 342  *\li   &lt;id, dest> is a unique tuple.  That means incoming messages
 343  *      are identifiable.
 344  *
 345  * Returns:
 346  *
 347  *\li   ISC_R_SUCCESS           -- all is well.
 348  *\li   ISC_R_NOMEMORY          -- memory could not be allocated.
 349  *\li   ISC_R_NOMORE            -- no more message ids can be allocated
 350  *                                 for this destination.
 351  */
 352
 353
 354 void
 355 dns_dispatch_removeresponse(dns_dispentry_t **resp,
 356                             dns_dispatchevent_t **sockevent);
 357 /*%<
 358  * Stops the flow of responses for the provided id and destination.
 359  * If "sockevent" is non-NULL, the dispatch event and associated buffer is
 360  * also returned to the system.
 361  *
 362  * Requires:
 363  *\li   "resp" != NULL and "*resp" contain a value previously allocated
 364  *      by dns_dispatch_addresponse();
 365  *
 366  *\li   May only be called from within the task given as the 'task'
 367  *      argument to dns_dispatch_addresponse() when allocating '*resp'.
 368  */
 369
 370
 371 isc_socket_t *
 372 dns_dispatch_getsocket(dns_dispatch_t *disp);
 373 /*%<
 374  * Return the socket associated with this dispatcher.
 375  *
 376  * Requires:
 377  *\li   disp is valid.
 378  *
 379  * Returns:
 380  *\li   The socket the dispatcher is using.
 381  */
 382
 383 isc_result_t
 384 dns_dispatch_getlocaladdress(dns_dispatch_t *disp, isc_sockaddr_t *addrp);
 385 /*%<
 386  * Return the local address for this dispatch.
 387  * This currently only works for dispatches using UDP sockets.
 388  *
 389  * Requires:
 390  *\li   disp is valid.
 391  *\li   addrp to be non null.
 392  *
 393  * Returns:
 394  *\li   ISC_R_SUCCESS
 395  *\li   ISC_R_NOTIMPLEMENTED
 396  */
 397
 398 void
 399 dns_dispatch_cancel(dns_dispatch_t *disp);
 400 /*%<
 401  * cancel outstanding clients
 402  *
 403  * Requires:
 404  *\li   disp is valid.
 405  */
 406
 407 void
 408 dns_dispatch_changeattributes(dns_dispatch_t *disp,
 409                               unsigned int attributes, unsigned int mask);
 410 /*%<
 411  * Set the bits described by "mask" to the corresponding values in
 412  * "attributes".
 413  *
 414  * That is:
 415  *
 416  * \code
 417  *      new = (old & ~mask) | (attributes & mask)
 418  * \endcode
 419  *
 420  * This function has a side effect when #DNS_DISPATCHATTR_NOLISTEN changes.
 421  * When the flag becomes off, the dispatch will start receiving on the
 422  * corresponding socket.  When the flag becomes on, receive events on the
 423  * corresponding socket will be canceled.
 424  *
 425  * Requires:
 426  *\li   disp is valid.
 427  *
 428  *\li   attributes are reasonable for the dispatch.  That is, setting the UDP
 429  *      attribute on a TCP socket isn't reasonable.
 430  */
 431
 432 void
 433 dns_dispatch_importrecv(dns_dispatch_t *disp, isc_event_t *event);
 434 /*%<
 435  * Inform the dispatcher of a socket receive.  This is used for sockets
 436  * shared between dispatchers and clients.  If the dispatcher fails to copy
 437  * or send the event, nothing happens.
 438  *
 439  * Requires:
 440  *\li   disp is valid, and the attribute DNS_DISPATCHATTR_NOLISTEN is set.
 441  *      event != NULL
 442  */
 443
 444 void
 445 dns_dispatch_hash(void *data, size_t len);
 446 /*%<
 447  * Feed 'data' to the dispatch query id generator where 'len' is the size
 448  * of 'data'.
 449  */
 450
 451 ISC_LANG_ENDDECLS
 452
 453 #endif /* DNS_DISPATCH_H */