val_kentry.h revision 269257
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 44struct packed_rrset_data; 45struct regional; 46struct 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 */ 55struct 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 */ 76struct 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 */ 92size_t key_entry_sizefunc(void* key, void* data); 93 94/** function for lruhash operation */ 95int key_entry_compfunc(void* k1, void* k2); 96 97/** function for lruhash operation */ 98void key_entry_delkeyfunc(void* key, void* userarg); 99 100/** function for lruhash operation */ 101void 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 */ 106void 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 */ 114struct 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 */ 122struct 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 */ 129int 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 */ 136int 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 */ 143int 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 */ 151void 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 */ 159char* 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 */ 171struct 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 */ 186struct 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 */ 200struct 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 */ 210struct 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 */ 218size_t key_entry_keysize(struct key_entry_key* kkey); 219 220#endif /* VALIDATOR_VAL_KENTRY_H */ 221