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#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 */ 56struct 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 */ 77struct 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 */ 95size_t key_entry_sizefunc(void* key, void* data); 96 97/** function for lruhash operation */ 98int key_entry_compfunc(void* k1, void* k2); 99 100/** function for lruhash operation */ 101void key_entry_delkeyfunc(void* key, void* userarg); 102 103/** function for lruhash operation */ 104void 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 */ 109void 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 */ 117struct 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 * @param copy_reason: if the reason string needs to be copied (allocated). 124 * @return newly allocated entry or NULL on a failure to allocate memory. 125 */ 126struct key_entry_key* key_entry_copy(struct key_entry_key* kkey, 127 int copy_reason); 128 129/** 130 * See if this is a null entry. Does not do locking. 131 * @param kkey: must have data pointer set correctly 132 * @return true if it is a NULL rrset entry. 133 */ 134int key_entry_isnull(struct key_entry_key* kkey); 135 136/** 137 * See if this entry is good. Does not do locking. 138 * @param kkey: must have data pointer set correctly 139 * @return true if it is good. 140 */ 141int key_entry_isgood(struct key_entry_key* kkey); 142 143/** 144 * See if this entry is bad. Does not do locking. 145 * @param kkey: must have data pointer set correctly 146 * @return true if it is bad. 147 */ 148int key_entry_isbad(struct key_entry_key* kkey); 149 150/** 151 * Get reason why a key is bad. 152 * @param kkey: bad key 153 * @return pointer to string. 154 * String is part of key entry and is deleted with it. 155 */ 156char* key_entry_get_reason(struct key_entry_key* kkey); 157 158/** 159 * Get the EDE (RFC8914) code why a key is bad. Can return LDNS_EDE_NONE. 160 * @param kkey: bad key 161 * @return the ede code. 162 */ 163sldns_ede_code key_entry_get_reason_bogus(struct key_entry_key* kkey); 164 165/** 166 * Create a null entry, in the given region. 167 * @param region: where to allocate 168 * @param name: the key name 169 * @param namelen: length of name 170 * @param dclass: class of key entry. (host order); 171 * @param ttl: what ttl should the key have. relative. 172 * @param reason_bogus: accompanying EDE code. 173 * @param reason: accompanying NULL-terminated EDE string (or NULL). 174 * @param now: current time (added to ttl). 175 * @return new key entry or NULL on alloc failure 176 */ 177struct key_entry_key* key_entry_create_null(struct regional* region, 178 uint8_t* name, size_t namelen, uint16_t dclass, time_t ttl, 179 sldns_ede_code reason_bogus, const char* reason, 180 time_t now); 181 182/** 183 * Create a key entry from an rrset, in the given region. 184 * @param region: where to allocate. 185 * @param name: the key name 186 * @param namelen: length of name 187 * @param dclass: class of key entry. (host order); 188 * @param rrset: data for key entry. This is copied to the region. 189 * @param sigalg: signalled algorithm list (or NULL). 190 * @param reason_bogus: accompanying EDE code (usually LDNS_EDE_NONE). 191 * @param reason: accompanying NULL-terminated EDE string (or NULL). 192 * @param now: current time (added to ttl of rrset) 193 * @return new key entry or NULL on alloc failure 194 */ 195struct key_entry_key* key_entry_create_rrset(struct regional* region, 196 uint8_t* name, size_t namelen, uint16_t dclass, 197 struct ub_packed_rrset_key* rrset, uint8_t* sigalg, 198 sldns_ede_code reason_bogus, const char* reason, 199 time_t now); 200 201/** 202 * Create a bad entry, in the given region. 203 * @param region: where to allocate 204 * @param name: the key name 205 * @param namelen: length of name 206 * @param dclass: class of key entry. (host order); 207 * @param ttl: what ttl should the key have. relative. 208 * @param reason_bogus: accompanying EDE code. 209 * @param reason: accompanying NULL-terminated EDE string (or NULL). 210 * @param now: current time (added to ttl). 211 * @return new key entry or NULL on alloc failure 212 */ 213struct key_entry_key* key_entry_create_bad(struct regional* region, 214 uint8_t* name, size_t namelen, uint16_t dclass, time_t ttl, 215 sldns_ede_code reason_bogus, const char* reason, 216 time_t now); 217 218/** 219 * Obtain rrset from a key entry, allocated in region. 220 * @param kkey: key entry to convert to a rrset. 221 * @param region: where to allocate rrset 222 * @return rrset copy; if no rrset or alloc error returns NULL. 223 */ 224struct ub_packed_rrset_key* key_entry_get_rrset(struct key_entry_key* kkey, 225 struct regional* region); 226 227/** 228 * Get keysize of the keyentry. 229 * @param kkey: key, must be a good key, with contents. 230 * @return size in bits of the key. 231 */ 232size_t key_entry_keysize(struct key_entry_key* kkey); 233 234#endif /* VALIDATOR_VAL_KENTRY_H */ 235