2 * Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 2000, 2001 Internet Software Consortium.
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.
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.
18 /* $Id: keytable.h,v 1.16 2007/06/19 23:47:16 tbox Exp $ */
20 #ifndef DNS_KEYTABLE_H
21 #define DNS_KEYTABLE_H 1
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.
34 *\li The module ensures appropriate synchronization of data structures it
35 * creates and manipulates.
41 *\li No anticipated impact.
46 #include <dns/types.h>
53 dns_keytable_create(isc_mem_t *mctx, dns_keytable_t **keytablep);
59 *\li 'mctx' is a valid memory context.
61 *\li keytablep != NULL && *keytablep == NULL
65 *\li On success, *keytablep is a valid, empty key table.
71 *\li Any other result indicates failure.
76 dns_keytable_attach(dns_keytable_t *source, dns_keytable_t **targetp);
78 * Attach *targetp to source.
82 *\li 'source' is a valid keytable.
84 *\li 'targetp' points to a NULL dns_keytable_t *.
88 *\li *targetp is attached to source.
92 dns_keytable_detach(dns_keytable_t **keytablep);
94 * Detach *keytablep from its keytable.
98 *\li 'keytablep' points to a valid keytable.
102 *\li *keytablep is NULL.
104 *\li If '*keytablep' is the last reference to the keytable,
105 * all resources used by the keytable will be freed
109 dns_keytable_add(dns_keytable_t *keytable, dst_key_t **keyp);
111 * Add '*keyp' to 'keytable'.
115 *\li Ownership of *keyp is transferred to the keytable.
119 *\li keyp != NULL && *keyp is a valid dst_key_t *.
123 *\li On success, *keyp == NULL
129 *\li Any other result indicates failure.
133 dns_keytable_findkeynode(dns_keytable_t *keytable, dns_name_t *name,
134 dns_secalg_t algorithm, dns_keytag_t tag,
135 dns_keynode_t **keynodep);
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.
143 *\li 'keytable' is a valid keytable.
145 *\li 'name' is a valid absolute name.
147 *\li keynodep != NULL && *keynodep == NULL
152 *\li DNS_R_PARTIALMATCH the name existed in the keytable.
155 *\li Any other result indicates an error.
159 dns_keytable_findnextkeynode(dns_keytable_t *keytable, dns_keynode_t *keynode,
160 dns_keynode_t **nextnodep);
162 * Search for the next key with the same properties as 'keynode' in
163 * 'keytable' as found by dns_keytable_findkeynode().
167 *\li 'keytable' is a valid keytable.
169 *\li 'keynode' is a valid keynode.
171 *\li nextnodep != NULL && *nextnodep == NULL
178 *\li Any other result indicates an error.
182 dns_keytable_finddeepestmatch(dns_keytable_t *keytable, dns_name_t *name,
183 dns_name_t *foundname);
185 * Search for the deepest match of 'name' in 'keytable'.
189 *\li 'keytable' is a valid keytable.
191 *\li 'name' is a valid absolute name.
193 *\li 'foundname' is a name with a dedicated buffer.
200 *\li Any other result indicates an error.
204 dns_keytable_detachkeynode(dns_keytable_t *keytable,
205 dns_keynode_t **keynodep);
207 * Give back a keynode found via dns_keytable_findkeynode().
211 *\li 'keytable' is a valid keytable.
213 *\li *keynodep is a valid keynode returned by a call to
214 * dns_keytable_findkeynode().
218 *\li *keynodep == NULL
222 dns_keytable_issecuredomain(dns_keytable_t *keytable, dns_name_t *name,
223 isc_boolean_t *wantdnssecp);
225 * Is 'name' at or beneath a trusted key?
229 *\li 'keytable' is a valid keytable.
231 *\li 'name' is a valid absolute name.
233 *\li '*wantsdnssecp' is a valid isc_boolean_t.
237 *\li On success, *wantsdnssecp will be ISC_TRUE if and only if 'name'
238 * is at or beneath a trusted key.
244 *\li Any other result is an error.
248 dns_keynode_key(dns_keynode_t *keynode);
250 * Get the DST key associated with keynode.
255 #endif /* DNS_KEYTABLE_H */