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

   1 /*
   2  * Copyright (C) 2004-2010, 2013  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2002  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: ncache.h,v 1.29 2010/05/14 23:50:40 tbox Exp $ */
  19
  20 #ifndef DNS_NCACHE_H
  21 #define DNS_NCACHE_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*! \file dns/ncache.h
  28  *\brief
  29  * DNS Ncache
  30  *
  31  * XXX TBS XXX
  32  *
  33  * MP:
  34  *\li   The caller must ensure any required synchronization.
  35  *
  36  * Reliability:
  37  *\li   No anticipated impact.
  38  *
  39  * Resources:
  40  *\li   TBS
  41  *
  42  * Security:
  43  *\li   No anticipated impact.
  44  *
  45  * Standards:
  46  *\li   RFC2308
  47  */
  48
  49 #include <isc/lang.h>
  50 #include <isc/stdtime.h>
  51
  52 #include <dns/types.h>
  53
  54 ISC_LANG_BEGINDECLS
  55
  56 /*%
  57  * _OMITDNSSEC:
  58  *      Omit DNSSEC records when rendering.
  59  */
  60 #define DNS_NCACHETOWIRE_OMITDNSSEC   0x0001
  61
  62 isc_result_t
  63 dns_ncache_add(dns_message_t *message, dns_db_t *cache, dns_dbnode_t *node,
  64                dns_rdatatype_t covers, isc_stdtime_t now, dns_ttl_t maxttl,
  65                dns_rdataset_t *addedrdataset);
  66 isc_result_t
  67 dns_ncache_addoptout(dns_message_t *message, dns_db_t *cache,
  68                      dns_dbnode_t *node, dns_rdatatype_t covers,
  69                      isc_stdtime_t now, dns_ttl_t maxttl,
  70                      isc_boolean_t optout, dns_rdataset_t *addedrdataset);
  71 /*%<
  72  * Convert the authority data from 'message' into a negative cache
  73  * rdataset, and store it in 'cache' at 'node' with a TTL limited to
  74  * 'maxttl'.
  75  *
  76  * \li dns_ncache_add produces a negative cache entry with a trust of no
  77  *     more than answer
  78  * \li dns_ncache_addoptout produces a negative cache entry which will have
  79  *     a trust of secure if all the records that make up the entry are secure.
  80  *
  81  * The 'covers' argument is the RR type whose nonexistence we are caching,
  82  * or dns_rdatatype_any when caching a NXDOMAIN response.
  83  *
  84  * 'optout' indicates a DNS_RDATASETATTR_OPTOUT should be set.
  85  *
  86  * Note:
  87  *\li   If 'addedrdataset' is not NULL, then it will be attached to the added
  88  *      rdataset.  See dns_db_addrdataset() for more details.
  89  *
  90  * Requires:
  91  *\li   'message' is a valid message with a properly formatting negative cache
  92  *      authority section.
  93  *
  94  *\li   The requirements of dns_db_addrdataset() apply to 'cache', 'node',
  95  *      'now', and 'addedrdataset'.
  96  *
  97  * Returns:
  98  *\li   #ISC_R_SUCCESS
  99  *\li   #ISC_R_NOSPACE
 100  *
 101  *\li   Any result code of dns_db_addrdataset() is a possible result code
 102  *      of dns_ncache_add().
 103  */
 104
 105 isc_result_t
 106 dns_ncache_towire(dns_rdataset_t *rdataset, dns_compress_t *cctx,
 107                   isc_buffer_t *target, unsigned int options,
 108                   unsigned int *countp);
 109 /*%<
 110  * Convert the negative caching rdataset 'rdataset' to wire format,
 111  * compressing names as specified in 'cctx', and storing the result in
 112  * 'target'.  If 'omit_dnssec' is set, DNSSEC records will not
 113  * be added to 'target'.
 114  *
 115  * Notes:
 116  *\li   The number of RRs added to target will be added to *countp.
 117  *
 118  * Requires:
 119  *\li   'rdataset' is a valid negative caching rdataset.
 120  *
 121  *\li   'rdataset' is not empty.
 122  *
 123  *\li   'countp' is a valid pointer.
 124  *
 125  * Ensures:
 126  *\li   On a return of ISC_R_SUCCESS, 'target' contains a wire format
 127  *      for the data contained in 'rdataset'.  Any error return leaves
 128  *      the buffer unchanged.
 129  *
 130  *\li   *countp has been incremented by the number of RRs added to
 131  *      target.
 132  *
 133  * Returns:
 134  *\li   #ISC_R_SUCCESS          - all ok
 135  *\li   #ISC_R_NOSPACE          - 'target' doesn't have enough room
 136  *
 137  *\li   Any error returned by dns_rdata_towire(), dns_rdataset_next(),
 138  *      dns_name_towire().
 139  */
 140
 141 isc_result_t
 142 dns_ncache_getrdataset(dns_rdataset_t *ncacherdataset, dns_name_t *name,
 143                        dns_rdatatype_t type, dns_rdataset_t *rdataset);
 144 /*%<
 145  * Search the negative caching rdataset for an rdataset with the
 146  * specified name and type.
 147  *
 148  * Requires:
 149  *\li   'ncacherdataset' is a valid negative caching rdataset.
 150  *
 151  *\li   'ncacherdataset' is not empty.
 152  *
 153  *\li   'name' is a valid name.
 154  *
 155  *\li   'type' is not SIG, or a meta-RR type.
 156  *
 157  *\li   'rdataset' is a valid disassociated rdataset.
 158  *
 159  * Ensures:
 160  *\li   On a return of ISC_R_SUCCESS, 'rdataset' is bound to the found
 161  *      rdataset.
 162  *
 163  * Returns:
 164  *\li   #ISC_R_SUCCESS          - the rdataset was found.
 165  *\li   #ISC_R_NOTFOUND         - the rdataset was not found.
 166  *
 167  */
 168
 169 isc_result_t
 170 dns_ncache_getsigrdataset(dns_rdataset_t *ncacherdataset, dns_name_t *name,
 171                           dns_rdatatype_t covers, dns_rdataset_t *rdataset);
 172 /*%<
 173  * Similar to dns_ncache_getrdataset() but get the rrsig that matches.
 174  */
 175
 176 void
 177 dns_ncache_current(dns_rdataset_t *ncacherdataset, dns_name_t *found,
 178                    dns_rdataset_t *rdataset);
 179
 180 /*%<
 181  * Extract the current rdataset and name from a ncache entry.
 182  *
 183  * Requires:
 184  * \li  'ncacherdataset' to be valid and to be a negative cache entry
 185  * \li  'found' to be valid.
 186  * \li  'rdataset' to be unassociated.
 187  */
 188
 189 ISC_LANG_ENDDECLS
 190
 191 #endif /* DNS_NCACHE_H */