unbound/validator/val_kentry.h

   1 /*
   2  * validator/val_kentry.h - validator key entry definition.
   3  *
   4  * Copyright (c) 2007, NLnet Labs. All rights reserved.
   5  *
   6  * This software is open source.
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions
  10  * are met:
  11  *
  12  * Redistributions of source code must retain the above copyright notice,
  13  * this list of conditions and the following disclaimer.
  14  *
  15  * Redistributions in binary form must reproduce the above copyright notice,
  16  * this list of conditions and the following disclaimer in the documentation
  17  * and/or other materials provided with the distribution.
  18  *
  19  * Neither the name of the NLNET LABS nor the names of its contributors may
  20  * be used to endorse or promote products derived from this software without
  21  * specific prior written permission.
  22  *
  23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  25  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  26  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  27  * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  28  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
  29  * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  30  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  31  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  32  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  33  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  34  */
  35
  36 /**
  37  * \file
  38  *
  39  * This file contains functions for dealing with validator key entries.
  40  */
  41
  42 #ifndef VALIDATOR_VAL_KENTRY_H
  43 #define VALIDATOR_VAL_KENTRY_H
  44 struct packed_rrset_data;
  45 struct regional;
  46 struct ub_packed_rrset_key;
  47 #include "util/storage/lruhash.h"
  48
  49 /**
  50  * A key entry for the validator.
  51  * This may or may not be a trusted key.
  52  * This is what is stored in the key cache.
  53  * This is the key part for the cache; the key entry key.
  54  */
  55 struct key_entry_key {
  56         /** lru hash entry */
  57         struct lruhash_entry entry;
  58         /** name of the key */
  59         uint8_t* name;
  60         /** length of name */
  61         size_t namelen;
  62         /** class of the key, host byteorder */
  63         uint16_t key_class;
  64 };
  65
  66 /**
  67  * Key entry for the validator.
  68  * Contains key status.
  69  * This is the data part for the cache, the key entry data.
  70  *
  71  * Can be in three basic states:
  72  *      isbad=0:                good key
  73  *      isbad=1:                bad key
  74  *      isbad=0 && rrset=0:     insecure space.
  75  */
  76 struct key_entry_data {
  77         /** the TTL of this entry (absolute time) */
  78         time_t ttl;
  79         /** the key rrdata. can be NULL to signal keyless name. */
  80         struct packed_rrset_data* rrset_data;
  81         /** not NULL sometimes to give reason why bogus */
  82         char* reason;
  83         /** list of algorithms signalled, ends with 0, or NULL */
  84         uint8_t* algo;
  85         /** DNS RR type of the rrset data (host order) */
  86         uint16_t rrset_type;
  87         /** if the key is bad: Bogus or malformed */
  88         uint8_t isbad;
  89 };
  90
  91 /** function for lruhash operation */
  92 size_t key_entry_sizefunc(void* key, void* data);
  93
  94 /** function for lruhash operation */
  95 int key_entry_compfunc(void* k1, void* k2);
  96
  97 /** function for lruhash operation */
  98 void key_entry_delkeyfunc(void* key, void* userarg);
  99
 100 /** function for lruhash operation */
 101 void key_entry_deldatafunc(void* data, void* userarg);
 102
 103 /** calculate hash for key entry
 104  * @param kk: key entry. The lruhash entry.hash value is filled in.
 105  */
 106 void key_entry_hash(struct key_entry_key* kk);
 107
 108 /**
 109  * Copy a key entry, to be region-allocated.
 110  * @param kkey: the key entry key (and data pointer) to copy.
 111  * @param region: where to allocate it
 112  * @return newly region-allocated entry or NULL on a failure to allocate.
 113  */
 114 struct key_entry_key* key_entry_copy_toregion(struct key_entry_key* kkey,
 115         struct regional* region);
 116
 117 /**
 118  * Copy a key entry, malloced.
 119  * @param kkey: the key entry key (and data pointer) to copy.
 120  * @return newly allocated entry or NULL on a failure to allocate memory.
 121  */
 122 struct key_entry_key* key_entry_copy(struct key_entry_key* kkey);
 123
 124 /**
 125  * See if this is a null entry. Does not do locking.
 126  * @param kkey: must have data pointer set correctly
 127  * @return true if it is a NULL rrset entry.
 128  */
 129 int key_entry_isnull(struct key_entry_key* kkey);
 130
 131 /**
 132  * See if this entry is good. Does not do locking.
 133  * @param kkey: must have data pointer set correctly
 134  * @return true if it is good.
 135  */
 136 int key_entry_isgood(struct key_entry_key* kkey);
 137
 138 /**
 139  * See if this entry is bad. Does not do locking.
 140  * @param kkey: must have data pointer set correctly
 141  * @return true if it is bad.
 142  */
 143 int key_entry_isbad(struct key_entry_key* kkey);
 144
 145 /**
 146  * Set reason why a key is bad.
 147  * @param kkey: bad key.
 148  * @param reason: string to attach, you must allocate it.
 149  *    Not safe to call twice unless you deallocate it yourself.
 150  */
 151 void key_entry_set_reason(struct key_entry_key* kkey, char* reason);
 152
 153 /**
 154  * Get reason why a key is bad.
 155  * @param kkey: bad key
 156  * @return pointer to string.
 157  *    String is part of key entry and is deleted with it.
 158  */
 159 char* key_entry_get_reason(struct key_entry_key* kkey);
 160
 161 /**
 162  * Create a null entry, in the given region.
 163  * @param region: where to allocate
 164  * @param name: the key name
 165  * @param namelen: length of name
 166  * @param dclass: class of key entry. (host order);
 167  * @param ttl: what ttl should the key have. relative.
 168  * @param now: current time (added to ttl).
 169  * @return new key entry or NULL on alloc failure
 170  */
 171 struct key_entry_key* key_entry_create_null(struct regional* region,
 172         uint8_t* name, size_t namelen, uint16_t dclass, time_t ttl,
 173         time_t now);
 174
 175 /**
 176  * Create a key entry from an rrset, in the given region.
 177  * @param region: where to allocate.
 178  * @param name: the key name
 179  * @param namelen: length of name
 180  * @param dclass: class of key entry. (host order);
 181  * @param rrset: data for key entry. This is copied to the region.
 182  * @param sigalg: signalled algorithm list (or NULL).
 183  * @param now: current time (added to ttl of rrset)
 184  * @return new key entry or NULL on alloc failure
 185  */
 186 struct key_entry_key* key_entry_create_rrset(struct regional* region,
 187         uint8_t* name, size_t namelen, uint16_t dclass,
 188         struct ub_packed_rrset_key* rrset, uint8_t* sigalg, time_t now);
 189
 190 /**
 191  * Create a bad entry, in the given region.
 192  * @param region: where to allocate
 193  * @param name: the key name
 194  * @param namelen: length of name
 195  * @param dclass: class of key entry. (host order);
 196  * @param ttl: what ttl should the key have. relative.
 197  * @param now: current time (added to ttl).
 198  * @return new key entry or NULL on alloc failure
 199  */
 200 struct key_entry_key* key_entry_create_bad(struct regional* region,
 201         uint8_t* name, size_t namelen, uint16_t dclass, time_t ttl,
 202         time_t now);
 203
 204 /**
 205  * Obtain rrset from a key entry, allocated in region.
 206  * @param kkey: key entry to convert to a rrset.
 207  * @param region: where to allocate rrset
 208  * @return rrset copy; if no rrset or alloc error returns NULL.
 209  */
 210 struct ub_packed_rrset_key* key_entry_get_rrset(struct key_entry_key* kkey,
 211         struct regional* region);
 212
 213 /**
 214  * Get keysize of the keyentry.
 215  * @param kkey: key, must be a good key, with contents.
 216  * @return size in bits of the key.
 217  */
 218 size_t key_entry_keysize(struct key_entry_key* kkey);
 219
 220 #endif /* VALIDATOR_VAL_KENTRY_H */