contrib/bind-9.2.4rc7/bin/named/include/named/client.h

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2001  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: client.h,v 1.60.2.4 2004/07/23 02:57:01 marka Exp $ */
  19
  20 #ifndef NAMED_CLIENT_H
  21 #define NAMED_CLIENT_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*
  28  * Client
  29  *
  30  * This module defines two objects, ns_client_t and ns_clientmgr_t.
  31  *
  32  * An ns_client_t object handles incoming DNS requests from clients
  33  * on a given network interface.
  34  *
  35  * Each ns_client_t object can handle only one TCP connection or UDP
  36  * request at a time.  Therefore, several ns_client_t objects are
  37  * typically created to serve each network interface, e.g., one
  38  * for handling TCP requests and a few (one per CPU) for handling
  39  * UDP requests.
  40  *
  41  * Incoming requests are classified as queries, zone transfer
  42  * requests, update requests, notify requests, etc, and handed off
  43  * to the appropriate request handler.  When the request has been
  44  * fully handled (which can be much later), the ns_client_t must be
  45  * notified of this by calling one of the following functions
  46  * exactly once in the context of its task:
  47  *
  48  *   ns_client_send()   (sending a non-error response)
  49  *   ns_client_sendraw() (sending a raw response)
  50  *   ns_client_error()  (sending an error response)
  51  *   ns_client_next()   (sending no response)
  52  *
  53  * This will release any resources used by the request and
  54  * and allow the ns_client_t to listen for the next request.
  55  *
  56  * A ns_clientmgr_t manages a number of ns_client_t objects.
  57  * New ns_client_t objects are created by calling
  58  * ns_clientmgr_createclients(). They are destroyed by
  59  * destroying their manager.
  60  */
  61
  62 /***
  63  *** Imports
  64  ***/
  65
  66 #include <isc/buffer.h>
  67 #include <isc/magic.h>
  68 #include <isc/stdtime.h>
  69 #include <isc/quota.h>
  70
  71 #include <dns/name.h>
  72 #include <dns/types.h>
  73 #include <dns/tcpmsg.h>
  74 #include <dns/fixedname.h>
  75 #include <named/types.h>
  76 #include <named/query.h>
  77
  78 /***
  79  *** Types
  80  ***/
  81
  82 typedef ISC_LIST(ns_client_t) client_list_t;
  83
  84 struct ns_client {
  85         unsigned int            magic;
  86         isc_mem_t *             mctx;
  87         ns_clientmgr_t *        manager;
  88         int                     state;
  89         int                     newstate;
  90         int                     naccepts;
  91         int                     nreads;
  92         int                     nsends;
  93         int                     nrecvs;
  94         int                     nupdates;
  95         int                     nctls;
  96         int                     references;
  97         unsigned int            attributes;
  98         isc_task_t *            task;
  99         dns_view_t *            view;
 100         dns_dispatch_t *        dispatch;
 101         isc_socket_t *          udpsocket;
 102         isc_socket_t *          tcplistener;
 103         isc_socket_t *          tcpsocket;
 104         unsigned char *         tcpbuf;
 105         dns_tcpmsg_t            tcpmsg;
 106         isc_boolean_t           tcpmsg_valid;
 107         isc_timer_t *           timer;
 108         isc_boolean_t           timerset;
 109         dns_message_t *         message;
 110         isc_socketevent_t *     sendevent;
 111         isc_socketevent_t *     recvevent;
 112         unsigned char *         recvbuf;
 113         dns_rdataset_t *        opt;
 114         isc_uint16_t            udpsize;
 115         isc_uint16_t            extflags;
 116         void                    (*next)(ns_client_t *);
 117         void                    (*shutdown)(void *arg, isc_result_t result);
 118         void                    *shutdown_arg;
 119         ns_query_t              query;
 120         isc_stdtime_t           requesttime;
 121         isc_stdtime_t           now;
 122         dns_name_t              signername;   /* [T]SIG key name */
 123         dns_name_t *            signer;       /* NULL if not valid sig */
 124         isc_boolean_t           mortal;       /* Die after handling request */
 125         isc_quota_t             *tcpquota;
 126         isc_quota_t             *recursionquota;
 127         ns_interface_t          *interface;
 128         isc_sockaddr_t          peeraddr;
 129         isc_boolean_t           peeraddr_valid;
 130         struct in6_pktinfo      pktinfo;
 131         isc_event_t             ctlevent;
 132         /*
 133          * Information about recent FORMERR response(s), for
 134          * FORMERR loop avoidance.  This is separate for each
 135          * client object rather than global only to avoid
 136          * the need for locking.
 137          */
 138         struct {
 139                 isc_sockaddr_t          addr;
 140                 isc_stdtime_t           time;
 141                 dns_messageid_t         id;
 142         } formerrcache;
 143         ISC_LINK(ns_client_t)   link;
 144         /*
 145          * The list 'link' is part of, or NULL if not on any list.
 146          */
 147         client_list_t           *list;
 148 };
 149
 150 #define NS_CLIENT_MAGIC                 ISC_MAGIC('N','S','C','c')
 151 #define NS_CLIENT_VALID(c)              ISC_MAGIC_VALID(c, NS_CLIENT_MAGIC)
 152
 153 #define NS_CLIENTATTR_TCP               0x01
 154 #define NS_CLIENTATTR_RA                0x02 /* Client gets recusive service */
 155 #define NS_CLIENTATTR_PKTINFO           0x04 /* pktinfo is valid */
 156 #define NS_CLIENTATTR_MULTICAST         0x08 /* recv'd from multicast */
 157
 158 /***
 159  *** Functions
 160  ***/
 161
 162 /*
 163  * Note!  These ns_client_ routines MUST be called ONLY from the client's
 164  * task in order to ensure synchronization.
 165  */
 166
 167 void
 168 ns_client_send(ns_client_t *client);
 169 /*
 170  * Finish processing the current client request and
 171  * send client->message as a response.
 172  */
 173
 174 void
 175 ns_client_sendraw(ns_client_t *client, dns_message_t *msg);
 176 /*
 177  * Finish processing the current client request and
 178  * send msg as a response using client->message->id for the id.
 179  */
 180
 181 void
 182 ns_client_error(ns_client_t *client, isc_result_t result);
 183 /*
 184  * Finish processing the current client request and return
 185  * an error response to the client.  The error response
 186  * will have an RCODE determined by 'result'.
 187  */
 188
 189 void
 190 ns_client_next(ns_client_t *client, isc_result_t result);
 191 /*
 192  * Finish processing the current client request,
 193  * return no response to the client.
 194  */
 195
 196 isc_boolean_t
 197 ns_client_shuttingdown(ns_client_t *client);
 198 /*
 199  * Return ISC_TRUE iff the client is currently shutting down.
 200  */
 201
 202 void
 203 ns_client_attach(ns_client_t *source, ns_client_t **target);
 204 /*
 205  * Attach '*targetp' to 'source'.
 206  */
 207
 208 void
 209 ns_client_detach(ns_client_t **clientp);
 210 /*
 211  * Detach '*clientp' from its client.
 212  */
 213
 214 isc_result_t
 215 ns_client_replace(ns_client_t *client);
 216 /*
 217  * Try to replace the current client with a new one, so that the
 218  * current one can go off and do some lengthy work without
 219  * leaving the dispatch/socket without service.
 220  */
 221
 222 void
 223 ns_client_settimeout(ns_client_t *client, unsigned int seconds);
 224 /*
 225  * Set a timer in the client to go off in the specified amount of time.
 226  */
 227
 228 isc_result_t
 229 ns_clientmgr_create(isc_mem_t *mctx, isc_taskmgr_t *taskmgr,
 230                     isc_timermgr_t *timermgr, ns_clientmgr_t **managerp);
 231 /*
 232  * Create a client manager.
 233  */
 234
 235 void
 236 ns_clientmgr_destroy(ns_clientmgr_t **managerp);
 237 /*
 238  * Destroy a client manager and all ns_client_t objects
 239  * managed by it.
 240  */
 241
 242 isc_result_t
 243 ns_clientmgr_createclients(ns_clientmgr_t *manager, unsigned int n,
 244                            ns_interface_t *ifp, isc_boolean_t tcp);
 245 /*
 246  * Create up to 'n' clients listening on interface 'ifp'.
 247  * If 'tcp' is ISC_TRUE, the clients will listen for TCP connections,
 248  * otherwise for UDP requests.
 249  */
 250
 251 isc_sockaddr_t *
 252 ns_client_getsockaddr(ns_client_t *client);
 253 /*
 254  * Get the socket address of the client whose request is
 255  * currently being processed.
 256  */
 257
 258 isc_result_t
 259 ns_client_checkaclsilent(ns_client_t  *client,dns_acl_t *acl,
 260                          isc_boolean_t default_allow);
 261
 262 /*
 263  * Convenience function for client request ACL checking.
 264  *
 265  * Check the current client request against 'acl'.  If 'acl'
 266  * is NULL, allow the request iff 'default_allow' is ISC_TRUE.
 267  *
 268  * Notes:
 269  *      This is appropriate for checking allow-update,
 270  *      allow-query, allow-transfer, etc.  It is not appropriate
 271  *      for checking the blackhole list because we treat positive
 272  *      matches as "allow" and negative matches as "deny"; in
 273  *      the case of the blackhole list this would be backwards.
 274  *
 275  * Requires:
 276  *      'client' points to a valid client.
 277  *      'acl' points to a valid ACL, or is NULL.
 278  *
 279  * Returns:
 280  *      ISC_R_SUCCESS   if the request should be allowed
 281  *      ISC_R_REFUSED   if the request should be denied
 282  *      No other return values are possible.
 283  */
 284
 285 isc_result_t
 286 ns_client_checkacl(ns_client_t  *client,
 287                    const char *opname, dns_acl_t *acl,
 288                    isc_boolean_t default_allow,
 289                    int log_level);
 290 /*
 291  * Like ns_client_checkacl, but also logs the outcome of the
 292  * check at log level 'log_level' if denied, and at debug 3
 293  * if approved.  Log messages will refer to the request as
 294  * an 'opname' request.
 295  *
 296  * Requires:
 297  *      Those of ns_client_checkaclsilent(), and:
 298  *
 299  *      'opname' points to a null-terminated string.
 300  */
 301
 302 void
 303 ns_client_log(ns_client_t *client, isc_logcategory_t *category,
 304               isc_logmodule_t *module, int level,
 305               const char *fmt, ...) ISC_FORMAT_PRINTF(5, 6);
 306
 307 void
 308 ns_client_aclmsg(const char *msg, dns_name_t *name, dns_rdataclass_t rdclass,
 309                  char *buf, size_t len);
 310
 311 #endif /* NAMED_CLIENT_H */