contrib/bind-9.5.2/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 */