1 /* 2 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 3 * 4 * This Source Code Form is subject to the terms of the Mozilla Public 5 * License, v. 2.0. If a copy of the MPL was not distributed with this 6 * file, You can obtain one at http://mozilla.org/MPL/2.0/. 7 * 8 * See the COPYRIGHT file distributed with this work for additional 9 * information regarding copyright ownership. 10 */ 11 12 #ifndef DNS_NTA_H 13 #define DNS_NTA_H 1 14 15 /***** 16 ***** Module Info 17 *****/ 18 19 /*! \file 20 * \brief 21 * The NTA module provides services for storing and retrieving negative 22 * trust anchors, and determine whether a given domain is subject to 23 * DNSSEC validation. 24 */ 25 26 #include <inttypes.h> 27 #include <stdbool.h> 28 29 #include <isc/buffer.h> 30 #include <isc/lang.h> 31 #include <isc/magic.h> 32 #include <isc/refcount.h> 33 #include <isc/rwlock.h> 34 #include <isc/stdtime.h> 35 #include <isc/task.h> 36 #include <isc/timer.h> 37 38 #include <dns/rdataset.h> 39 #include <dns/resolver.h> 40 #include <dns/types.h> 41 #include <dns/view.h> 42 43 ISC_LANG_BEGINDECLS 44 45 struct dns_ntatable { 46 /* Unlocked. */ 47 unsigned int magic; 48 dns_view_t * view; 49 isc_rwlock_t rwlock; 50 isc_taskmgr_t * taskmgr; 51 isc_timermgr_t *timermgr; 52 isc_task_t * task; 53 /* Protected by atomics */ 54 isc_refcount_t references; 55 /* Locked by rwlock. */ 56 dns_rbt_t *table; 57 }; 58 59 #define NTATABLE_MAGIC ISC_MAGIC('N', 'T', 'A', 't') 60 #define VALID_NTATABLE(nt) ISC_MAGIC_VALID(nt, NTATABLE_MAGIC) 61 62 isc_result_t 63 dns_ntatable_create(dns_view_t *view, isc_taskmgr_t *taskmgr, 64 isc_timermgr_t *timermgr, dns_ntatable_t **ntatablep); 65 /*%< 66 * Create an NTA table in view 'view'. 67 * 68 * Requires: 69 * 70 *\li 'view' is a valid view. 71 * 72 *\li 'tmgr' is a valid timer manager. 73 * 74 *\li ntatablep != NULL && *ntatablep == NULL 75 * 76 * Ensures: 77 * 78 *\li On success, *ntatablep is a valid, empty NTA table. 79 * 80 * Returns: 81 * 82 *\li ISC_R_SUCCESS 83 *\li Any other result indicates failure. 84 */ 85 86 void 87 dns_ntatable_attach(dns_ntatable_t *source, dns_ntatable_t **targetp); 88 /*%< 89 * Attach *targetp to source. 90 * 91 * Requires: 92 * 93 *\li 'source' is a valid ntatable. 94 * 95 *\li 'targetp' points to a NULL dns_ntatable_t *. 96 * 97 * Ensures: 98 * 99 *\li *targetp is attached to source. 100 */ 101 102 void 103 dns_ntatable_detach(dns_ntatable_t **ntatablep); 104 /*%< 105 * Detach *ntatablep from its ntatable. 106 * 107 * Requires: 108 * 109 *\li 'ntatablep' points to a valid ntatable. 110 * 111 * Ensures: 112 * 113 *\li *ntatablep is NULL. 114 * 115 *\li If '*ntatablep' is the last reference to the ntatable, 116 * all resources used by the ntatable will be freed 117 */ 118 119 isc_result_t 120 dns_ntatable_add(dns_ntatable_t *ntatable, const dns_name_t *name, bool force, 121 isc_stdtime_t now, uint32_t lifetime); 122 /*%< 123 * Add a negative trust anchor to 'ntatable' for name 'name', 124 * which will expire at time 'now' + 'lifetime'. If 'force' is true, 125 * then the NTA will persist for the entire specified lifetime. 126 * If it is false, then the name will be queried periodically and 127 * validation will be attempted to see whether it's still bogus; 128 * if validation is successful, the NTA will be allowed to expire 129 * early and validation below the NTA will resume. 130 * 131 * Notes: 132 * 133 *\li If an NTA already exists in the table, its expiry time 134 * is updated. 135 * 136 * Requires: 137 * 138 *\li 'ntatable' points to a valid ntatable. 139 * 140 *\li 'name' points to a valid name. 141 * 142 * Returns: 143 * 144 *\li ISC_R_SUCCESS 145 * 146 *\li Any other result indicates failure. 147 */ 148 149 isc_result_t 150 dns_ntatable_delete(dns_ntatable_t *ntatable, const dns_name_t *keyname); 151 /*%< 152 * Delete node(s) from 'ntatable' matching name 'keyname' 153 * 154 * Requires: 155 * 156 *\li 'ntatable' points to a valid ntatable. 157 * 158 *\li 'name' is not NULL 159 * 160 * Returns: 161 * 162 *\li ISC_R_SUCCESS 163 * 164 *\li Any other result indicates failure. 165 */ 166 167 bool 168 dns_ntatable_covered(dns_ntatable_t *ntatable, isc_stdtime_t now, 169 const dns_name_t *name, const dns_name_t *anchor); 170 /*%< 171 * Return true if 'name' is below a non-expired negative trust 172 * anchor which in turn is at or below 'anchor'. 173 * 174 * If 'ntatable' has not been initialized, return false. 175 * 176 * Requires: 177 * 178 *\li 'ntatable' is NULL or is a valid ntatable. 179 * 180 *\li 'name' is a valid absolute name. 181 */ 182 183 isc_result_t 184 dns_ntatable_totext(dns_ntatable_t *ntatable, const char *view, 185 isc_buffer_t **buf); 186 /*%< 187 * Dump the NTA table to buffer at 'buf', with view names 188 * 189 * Requires: 190 * \li "ntatable" is a valid table. 191 * 192 * \li "*buf" is a valid buffer. 193 */ 194 195 isc_result_t 196 dns_ntatable_dump(dns_ntatable_t *ntatable, FILE *fp); 197 /*%< 198 * Dump the NTA table to the file opened as 'fp'. 199 */ 200 201 isc_result_t 202 dns_ntatable_save(dns_ntatable_t *ntatable, FILE *fp); 203 /*%< 204 * Save the NTA table to the file opened as 'fp', for later loading. 205 */ 206 ISC_LANG_ENDDECLS 207 208 #endif /* DNS_NTA_H */ 209