contrib/bind-9.3/lib/dns/include/dns/keytable.h

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