keytable.h revision 222395
1/* 2 * Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") 3 * Copyright (C) 2000, 2001 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: keytable.h,v 1.16 2007-06-19 23:47:16 tbox Exp $ */ 19 20#ifndef DNS_KEYTABLE_H 21#define DNS_KEYTABLE_H 1 22 23/***** 24 ***** Module Info 25 *****/ 26 27/*! \file 28 * \brief 29 * The keytable module provides services for storing and retrieving DNSSEC 30 * trusted keys, as well as the ability to find the deepest matching key 31 * for a given domain name. 32 * 33 * MP: 34 *\li The module ensures appropriate synchronization of data structures it 35 * creates and manipulates. 36 * 37 * Resources: 38 *\li TBS 39 * 40 * Security: 41 *\li No anticipated impact. 42 */ 43 44#include <isc/lang.h> 45 46#include <dns/types.h> 47 48#include <dst/dst.h> 49 50ISC_LANG_BEGINDECLS 51 52isc_result_t 53dns_keytable_create(isc_mem_t *mctx, dns_keytable_t **keytablep); 54/*%< 55 * Create a keytable. 56 * 57 * Requires: 58 * 59 *\li 'mctx' is a valid memory context. 60 * 61 *\li keytablep != NULL && *keytablep == NULL 62 * 63 * Ensures: 64 * 65 *\li On success, *keytablep is a valid, empty key table. 66 * 67 * Returns: 68 * 69 *\li ISC_R_SUCCESS 70 * 71 *\li Any other result indicates failure. 72 */ 73 74 75void 76dns_keytable_attach(dns_keytable_t *source, dns_keytable_t **targetp); 77/*%< 78 * Attach *targetp to source. 79 * 80 * Requires: 81 * 82 *\li 'source' is a valid keytable. 83 * 84 *\li 'targetp' points to a NULL dns_keytable_t *. 85 * 86 * Ensures: 87 * 88 *\li *targetp is attached to source. 89 */ 90 91void 92dns_keytable_detach(dns_keytable_t **keytablep); 93/*%< 94 * Detach *keytablep from its keytable. 95 * 96 * Requires: 97 * 98 *\li 'keytablep' points to a valid keytable. 99 * 100 * Ensures: 101 * 102 *\li *keytablep is NULL. 103 * 104 *\li If '*keytablep' is the last reference to the keytable, 105 * all resources used by the keytable will be freed 106 */ 107 108isc_result_t 109dns_keytable_add(dns_keytable_t *keytable, dst_key_t **keyp); 110/*%< 111 * Add '*keyp' to 'keytable'. 112 * 113 * Notes: 114 * 115 *\li Ownership of *keyp is transferred to the keytable. 116 * 117 * Requires: 118 * 119 *\li keyp != NULL && *keyp is a valid dst_key_t *. 120 * 121 * Ensures: 122 * 123 *\li On success, *keyp == NULL 124 * 125 * Returns: 126 * 127 *\li ISC_R_SUCCESS 128 * 129 *\li Any other result indicates failure. 130 */ 131 132isc_result_t 133dns_keytable_findkeynode(dns_keytable_t *keytable, dns_name_t *name, 134 dns_secalg_t algorithm, dns_keytag_t tag, 135 dns_keynode_t **keynodep); 136/*%< 137 * Search for a key named 'name', matching 'algorithm' and 'tag' in 138 * 'keytable'. This finds the first instance which matches. Use 139 * dns_keytable_findnextkeynode() to find other instances. 140 * 141 * Requires: 142 * 143 *\li 'keytable' is a valid keytable. 144 * 145 *\li 'name' is a valid absolute name. 146 * 147 *\li keynodep != NULL && *keynodep == NULL 148 * 149 * Returns: 150 * 151 *\li ISC_R_SUCCESS 152 *\li DNS_R_PARTIALMATCH the name existed in the keytable. 153 *\li ISC_R_NOTFOUND 154 * 155 *\li Any other result indicates an error. 156 */ 157 158isc_result_t 159dns_keytable_findnextkeynode(dns_keytable_t *keytable, dns_keynode_t *keynode, 160 dns_keynode_t **nextnodep); 161/*%< 162 * Search for the next key with the same properties as 'keynode' in 163 * 'keytable' as found by dns_keytable_findkeynode(). 164 * 165 * Requires: 166 * 167 *\li 'keytable' is a valid keytable. 168 * 169 *\li 'keynode' is a valid keynode. 170 * 171 *\li nextnodep != NULL && *nextnodep == NULL 172 * 173 * Returns: 174 * 175 *\li ISC_R_SUCCESS 176 *\li ISC_R_NOTFOUND 177 * 178 *\li Any other result indicates an error. 179 */ 180 181isc_result_t 182dns_keytable_finddeepestmatch(dns_keytable_t *keytable, dns_name_t *name, 183 dns_name_t *foundname); 184/*%< 185 * Search for the deepest match of 'name' in 'keytable'. 186 * 187 * Requires: 188 * 189 *\li 'keytable' is a valid keytable. 190 * 191 *\li 'name' is a valid absolute name. 192 * 193 *\li 'foundname' is a name with a dedicated buffer. 194 * 195 * Returns: 196 * 197 *\li ISC_R_SUCCESS 198 *\li ISC_R_NOTFOUND 199 * 200 *\li Any other result indicates an error. 201 */ 202 203void 204dns_keytable_detachkeynode(dns_keytable_t *keytable, 205 dns_keynode_t **keynodep); 206/*%< 207 * Give back a keynode found via dns_keytable_findkeynode(). 208 * 209 * Requires: 210 * 211 *\li 'keytable' is a valid keytable. 212 * 213 *\li *keynodep is a valid keynode returned by a call to 214 * dns_keytable_findkeynode(). 215 * 216 * Ensures: 217 * 218 *\li *keynodep == NULL 219 */ 220 221isc_result_t 222dns_keytable_issecuredomain(dns_keytable_t *keytable, dns_name_t *name, 223 isc_boolean_t *wantdnssecp); 224/*%< 225 * Is 'name' at or beneath a trusted key? 226 * 227 * Requires: 228 * 229 *\li 'keytable' is a valid keytable. 230 * 231 *\li 'name' is a valid absolute name. 232 * 233 *\li '*wantsdnssecp' is a valid isc_boolean_t. 234 * 235 * Ensures: 236 * 237 *\li On success, *wantsdnssecp will be ISC_TRUE if and only if 'name' 238 * is at or beneath a trusted key. 239 * 240 * Returns: 241 * 242 *\li ISC_R_SUCCESS 243 * 244 *\li Any other result is an error. 245 */ 246 247dst_key_t * 248dns_keynode_key(dns_keynode_t *keynode); 249/*%< 250 * Get the DST key associated with keynode. 251 */ 252 253ISC_LANG_ENDDECLS 254 255#endif /* DNS_KEYTABLE_H */ 256