BIND: update vendor tree to 9.5.2-P2
[dragonfly.git] / contrib / bind / lib / dns / include / dns / keytable.h
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
50 ISC_LANG_BEGINDECLS
51
52 isc_result_t
53 dns_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
75 void
76 dns_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
91 void
92 dns_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
108 isc_result_t
109 dns_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
132 isc_result_t
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);
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
158 isc_result_t
159 dns_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
181 isc_result_t
182 dns_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
203 void
204 dns_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
221 isc_result_t
222 dns_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
247 dst_key_t *
248 dns_keynode_key(dns_keynode_t *keynode);
249 /*%<
250  * Get the DST key associated with keynode.
251  */
252
253 ISC_LANG_ENDDECLS
254
255 #endif /* DNS_KEYTABLE_H */