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 #include "sldns/rrdef.h" 49 50 /** 51 * A key entry for the validator. 52 * This may or may not be a trusted key. 53 * This is what is stored in the key cache. 54 * This is the key part for the cache; the key entry key. 55 */ 56 struct key_entry_key { 57 /** lru hash entry */ 58 struct lruhash_entry entry; 59 /** name of the key */ 60 uint8_t* name; 61 /** length of name */ 62 size_t namelen; 63 /** class of the key, host byteorder */ 64 uint16_t key_class; 65 }; 66 67 /** 68 * Key entry for the validator. 69 * Contains key status. 70 * This is the data part for the cache, the key entry data. 71 * 72 * Can be in three basic states: 73 * isbad=0: good key 74 * isbad=1: bad key 75 * isbad=0 && rrset=0: insecure space. 76 */ 77 struct key_entry_data { 78 /** the TTL of this entry (absolute time) */ 79 time_t ttl; 80 /** the key rrdata. can be NULL to signal keyless name. */ 81 struct packed_rrset_data* rrset_data; 82 /** not NULL sometimes to give reason why bogus */ 83 char* reason; 84 /** not NULL to give reason why bogus */ 85 sldns_ede_code reason_bogus; 86 /** list of algorithms signalled, ends with 0, or NULL */ 87 uint8_t* algo; 88 /** DNS RR type of the rrset data (host order) */ 89 uint16_t rrset_type; 90 /** if the key is bad: Bogus or malformed */ 91 uint8_t isbad; 92 }; 93 94 /** function for lruhash operation */ 95 size_t key_entry_sizefunc(void* key, void* data); 96 97 /** function for lruhash operation */ 98 int key_entry_compfunc(void* k1, void* k2); 99 100 /** function for lruhash operation */ 101 void key_entry_delkeyfunc(void* key, void* userarg); 102 103 /** function for lruhash operation */ 104 void key_entry_deldatafunc(void* data, void* userarg); 105 106 /** calculate hash for key entry 107 * @param kk: key entry. The lruhash entry.hash value is filled in. 108 */ 109 void key_entry_hash(struct key_entry_key* kk); 110 111 /** 112 * Copy a key entry, to be region-allocated. 113 * @param kkey: the key entry key (and data pointer) to copy. 114 * @param region: where to allocate it 115 * @return newly region-allocated entry or NULL on a failure to allocate. 116 */ 117 struct key_entry_key* key_entry_copy_toregion(struct key_entry_key* kkey, 118 struct regional* region); 119 120 /** 121 * Copy a key entry, malloced. 122 * @param kkey: the key entry key (and data pointer) to copy. 123 * @return newly allocated entry or NULL on a failure to allocate memory. 124 */ 125 struct key_entry_key* key_entry_copy(struct key_entry_key* kkey); 126 127 /** 128 * See if this is a null entry. Does not do locking. 129 * @param kkey: must have data pointer set correctly 130 * @return true if it is a NULL rrset entry. 131 */ 132 int key_entry_isnull(struct key_entry_key* kkey); 133 134 /** 135 * See if this entry is good. Does not do locking. 136 * @param kkey: must have data pointer set correctly 137 * @return true if it is good. 138 */ 139 int key_entry_isgood(struct key_entry_key* kkey); 140 141 /** 142 * See if this entry is bad. Does not do locking. 143 * @param kkey: must have data pointer set correctly 144 * @return true if it is bad. 145 */ 146 int key_entry_isbad(struct key_entry_key* kkey); 147 148 /** 149 * Set reason why a key is bad. 150 * @param kkey: bad key. 151 * @param reason: string to attach, you must allocate it. 152 * Not safe to call twice unless you deallocate it yourself. 153 */ 154 void key_entry_set_reason(struct key_entry_key* kkey, char* reason); 155 156 /** 157 * Set the EDE (RFC8914) code why the key is bad, if it 158 * exists (so not LDNS_EDE_NONE). 159 * @param kkey: bad key. 160 * @param ede: EDE code to attach to this key. 161 */ 162 void key_entry_set_reason_bogus(struct key_entry_key* kkey, sldns_ede_code ede); 163 164 165 /** 166 * Get reason why a key is bad. 167 * @param kkey: bad key 168 * @return pointer to string. 169 * String is part of key entry and is deleted with it. 170 */ 171 char* key_entry_get_reason(struct key_entry_key* kkey); 172 173 /** 174 * Get the EDE (RFC8914) code why a key is bad. Can return LDNS_EDE_NONE. 175 * @param kkey: bad key 176 * @return the ede code. 177 */ 178 sldns_ede_code key_entry_get_reason_bogus(struct key_entry_key* kkey); 179 180 /** 181 * Create a null entry, in the given region. 182 * @param region: where to allocate 183 * @param name: the key name 184 * @param namelen: length of name 185 * @param dclass: class of key entry. (host order); 186 * @param ttl: what ttl should the key have. relative. 187 * @param now: current time (added to ttl). 188 * @return new key entry or NULL on alloc failure 189 */ 190 struct key_entry_key* key_entry_create_null(struct regional* region, 191 uint8_t* name, size_t namelen, uint16_t dclass, time_t ttl, 192 time_t now); 193 194 /** 195 * Create a key entry from an rrset, in the given region. 196 * @param region: where to allocate. 197 * @param name: the key name 198 * @param namelen: length of name 199 * @param dclass: class of key entry. (host order); 200 * @param rrset: data for key entry. This is copied to the region. 201 * @param sigalg: signalled algorithm list (or NULL). 202 * @param now: current time (added to ttl of rrset) 203 * @return new key entry or NULL on alloc failure 204 */ 205 struct key_entry_key* key_entry_create_rrset(struct regional* region, 206 uint8_t* name, size_t namelen, uint16_t dclass, 207 struct ub_packed_rrset_key* rrset, uint8_t* sigalg, time_t now); 208 209 /** 210 * Create a bad entry, in the given region. 211 * @param region: where to allocate 212 * @param name: the key name 213 * @param namelen: length of name 214 * @param dclass: class of key entry. (host order); 215 * @param ttl: what ttl should the key have. relative. 216 * @param now: current time (added to ttl). 217 * @return new key entry or NULL on alloc failure 218 */ 219 struct key_entry_key* key_entry_create_bad(struct regional* region, 220 uint8_t* name, size_t namelen, uint16_t dclass, time_t ttl, 221 time_t now); 222 223 /** 224 * Obtain rrset from a key entry, allocated in region. 225 * @param kkey: key entry to convert to a rrset. 226 * @param region: where to allocate rrset 227 * @return rrset copy; if no rrset or alloc error returns NULL. 228 */ 229 struct ub_packed_rrset_key* key_entry_get_rrset(struct key_entry_key* kkey, 230 struct regional* region); 231 232 /** 233 * Get keysize of the keyentry. 234 * @param kkey: key, must be a good key, with contents. 235 * @return size in bits of the key. 236 */ 237 size_t key_entry_keysize(struct key_entry_key* kkey); 238 239 #endif /* VALIDATOR_VAL_KENTRY_H */ 240