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