unbound/validator/val_sigcrypt.h

   1 /*
   2  * validator/val_sigcrypt.h - validator signature crypto functions.
   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 helper functions for the validator module.
  40  * The functions help with signature verification and checking, the
  41  * bridging between RR wireformat data and crypto calls.
  42  */
  43
  44 #ifndef VALIDATOR_VAL_SIGCRYPT_H
  45 #define VALIDATOR_VAL_SIGCRYPT_H
  46 #include "util/data/packed_rrset.h"
  47 struct val_env;
  48 struct module_env;
  49 struct ub_packed_rrset_key;
  50 struct rbtree_t;
  51 struct regional;
  52 struct sldns_buffer;
  53
  54 /** number of entries in algorithm needs array */
  55 #define ALGO_NEEDS_MAX 256
  56
  57 /**
  58  * Storage for algorithm needs.  DNSKEY algorithms.
  59  */
  60 struct algo_needs {
  61         /** the algorithms (8-bit) with each a number.
  62          * 0: not marked.
  63          * 1: marked 'necessary but not yet fulfilled'
  64          * 2: marked bogus.
  65          * Indexed by algorithm number.
  66          */
  67         uint8_t needs[ALGO_NEEDS_MAX];
  68         /** the number of entries in the array that are unfulfilled */
  69         size_t num;
  70 };
  71
  72 /**
  73  * Initialize algo needs structure, set algos from rrset as needed.
  74  * Results are added to an existing need structure.
  75  * @param n: struct with storage.
  76  * @param dnskey: algos from this struct set as necessary. DNSKEY set.
  77  * @param sigalg: adds to signalled algorithm list too.
  78  */
  79 void algo_needs_init_dnskey_add(struct algo_needs* n,
  80         struct ub_packed_rrset_key* dnskey, uint8_t* sigalg);
  81
  82 /**
  83  * Initialize algo needs structure from a signalled algo list.
  84  * @param n: struct with storage.
  85  * @param sigalg: signalled algorithm list, numbers ends with 0.
  86  */
  87 void algo_needs_init_list(struct algo_needs* n, uint8_t* sigalg);
  88
  89 /**
  90  * Initialize algo needs structure, set algos from rrset as needed.
  91  * @param n: struct with storage.
  92  * @param ds: algos from this struct set as necessary. DS set.
  93  * @param fav_ds_algo: filter to use only this DS algo.
  94  * @param sigalg: list of signalled algos, constructed as output,
  95  *      provide size ALGO_NEEDS_MAX+1. list of algonumbers, ends with a zero.
  96  */
  97 void algo_needs_init_ds(struct algo_needs* n, struct ub_packed_rrset_key* ds,
  98         int fav_ds_algo, uint8_t* sigalg);
  99
 100 /**
 101  * Mark this algorithm as a success, sec_secure, and see if we are done.
 102  * @param n: storage structure processed.
 103  * @param algo: the algorithm processed to be secure.
 104  * @return if true, processing has finished successfully, we are satisfied.
 105  */
 106 int algo_needs_set_secure(struct algo_needs* n, uint8_t algo);
 107
 108 /**
 109  * Mark this algorithm a failure, sec_bogus.  It can later be overridden
 110  * by a success for this algorithm (with a different signature).
 111  * @param n: storage structure processed.
 112  * @param algo: the algorithm processed to be bogus.
 113  */
 114 void algo_needs_set_bogus(struct algo_needs* n, uint8_t algo);
 115
 116 /**
 117  * See how many algorithms are missing (not bogus or secure, but not processed)
 118  * @param n: storage structure processed.
 119  * @return number of algorithms missing after processing.
 120  */
 121 size_t algo_needs_num_missing(struct algo_needs* n);
 122
 123 /**
 124  * See which algo is missing.
 125  * @param n: struct after processing.
 126  * @return if 0 an algorithm was bogus, if a number, this algorithm was
 127  *   missing.  So on 0, report why that was bogus, on number report a missing
 128  *   algorithm.  There could be multiple missing, this reports the first one.
 129  */
 130 int algo_needs_missing(struct algo_needs* n);
 131
 132 /**
 133  * Format error reason for algorithm missing.
 134  * @param env: module env with scratch for temp storage of string.
 135  * @param alg: DNSKEY-algorithm missing.
 136  * @param reason: destination.
 137  * @param s: string, appended with 'with algorithm ..'.
 138  */
 139 void algo_needs_reason(struct module_env* env, int alg, char** reason, char* s);
 140
 141 /**
 142  * Check if dnskey matches a DS digest
 143  * Does not check dnskey-keyid footprint, just the digest.
 144  * @param env: module environment. Uses scratch space.
 145  * @param dnskey_rrset: DNSKEY rrset.
 146  * @param dnskey_idx: index of RR in rrset.
 147  * @param ds_rrset: DS rrset
 148  * @param ds_idx: index of RR in DS rrset.
 149  * @return true if it matches, false on error, not supported or no match.
 150  */
 151 int ds_digest_match_dnskey(struct module_env* env,
 152         struct ub_packed_rrset_key* dnskey_rrset, size_t dnskey_idx,
 153         struct ub_packed_rrset_key* ds_rrset, size_t ds_idx);
 154
 155 /**
 156  * Get dnskey keytag, footprint value
 157  * @param dnskey_rrset: DNSKEY rrset.
 158  * @param dnskey_idx: index of RR in rrset.
 159  * @return the keytag or 0 for badly formatted DNSKEYs.
 160  */
 161 uint16_t dnskey_calc_keytag(struct ub_packed_rrset_key* dnskey_rrset,
 162         size_t dnskey_idx);
 163
 164 /**
 165  * Get DS keytag, footprint value that matches the DNSKEY keytag it signs.
 166  * @param ds_rrset: DS rrset
 167  * @param ds_idx: index of RR in DS rrset.
 168  * @return the keytag or 0 for badly formatted DSs.
 169  */
 170 uint16_t ds_get_keytag(struct ub_packed_rrset_key* ds_rrset, size_t ds_idx);
 171
 172 /**
 173  * See if DNSKEY algorithm is supported
 174  * @param dnskey_rrset: DNSKEY rrset.
 175  * @param dnskey_idx: index of RR in rrset.
 176  * @return true if supported.
 177  */
 178 int dnskey_algo_is_supported(struct ub_packed_rrset_key* dnskey_rrset,
 179         size_t dnskey_idx);
 180
 181 /**
 182  * See if DS digest algorithm is supported
 183  * @param ds_rrset: DS rrset
 184  * @param ds_idx: index of RR in DS rrset.
 185  * @return true if supported.
 186  */
 187 int ds_digest_algo_is_supported(struct ub_packed_rrset_key* ds_rrset,
 188         size_t ds_idx);
 189
 190 /**
 191  * Get DS RR digest algorithm
 192  * @param ds_rrset: DS rrset.
 193  * @param ds_idx: which DS.
 194  * @return algorithm or 0 if DS too short.
 195  */
 196 int ds_get_digest_algo(struct ub_packed_rrset_key* ds_rrset, size_t ds_idx);
 197
 198 /**
 199  * See if DS key algorithm is supported
 200  * @param ds_rrset: DS rrset
 201  * @param ds_idx: index of RR in DS rrset.
 202  * @return true if supported.
 203  */
 204 int ds_key_algo_is_supported(struct ub_packed_rrset_key* ds_rrset,
 205         size_t ds_idx);
 206
 207 /**
 208  * Get DS RR key algorithm. This value should match with the DNSKEY algo.
 209  * @param k: DS rrset.
 210  * @param idx: which DS.
 211  * @return algorithm or 0 if DS too short.
 212  */
 213 int ds_get_key_algo(struct ub_packed_rrset_key* k, size_t idx);
 214
 215 /**
 216  * Get DNSKEY RR signature algorithm
 217  * @param k: DNSKEY rrset.
 218  * @param idx: which DNSKEY RR.
 219  * @return algorithm or 0 if DNSKEY too short.
 220  */
 221 int dnskey_get_algo(struct ub_packed_rrset_key* k, size_t idx);
 222
 223 /**
 224  * Get DNSKEY RR flags
 225  * @param k: DNSKEY rrset.
 226  * @param idx: which DNSKEY RR.
 227  * @return flags or 0 if DNSKEY too short.
 228  */
 229 uint16_t dnskey_get_flags(struct ub_packed_rrset_key* k, size_t idx);
 230
 231 /**
 232  * Verify rrset against dnskey rrset.
 233  * @param env: module environment, scratch space is used.
 234  * @param ve: validator environment, date settings.
 235  * @param rrset: to be validated.
 236  * @param dnskey: DNSKEY rrset, keyset to try.
 237  * @param sigalg: if nonNULL provide downgrade protection otherwise one
 238  *   algorithm is enough.
 239  * @param reason: if bogus, a string returned, fixed or alloced in scratch.
 240  * @return SECURE if one key in the set verifies one rrsig.
 241  *      UNCHECKED on allocation errors, unsupported algorithms, malformed data,
 242  *      and BOGUS on verification failures (no keys match any signatures).
 243  */
 244 enum sec_status dnskeyset_verify_rrset(struct module_env* env,
 245         struct val_env* ve, struct ub_packed_rrset_key* rrset,
 246         struct ub_packed_rrset_key* dnskey, uint8_t* sigalg, char** reason);
 247
 248 /**
 249  * verify rrset against one specific dnskey (from rrset)
 250  * @param env: module environment, scratch space is used.
 251  * @param ve: validator environment, date settings.
 252  * @param rrset: to be validated.
 253  * @param dnskey: DNSKEY rrset, keyset.
 254  * @param dnskey_idx: which key from the rrset to try.
 255  * @param reason: if bogus, a string returned, fixed or alloced in scratch.
 256  * @return secure if *this* key signs any of the signatures on rrset.
 257  *      unchecked on error or and bogus on bad signature.
 258  */
 259 enum sec_status dnskey_verify_rrset(struct module_env* env,
 260         struct val_env* ve, struct ub_packed_rrset_key* rrset,
 261         struct ub_packed_rrset_key* dnskey, size_t dnskey_idx, char** reason);
 262
 263 /**
 264  * verify rrset, with dnskey rrset, for a specific rrsig in rrset
 265  * @param env: module environment, scratch space is used.
 266  * @param ve: validator environment, date settings.
 267  * @param now: current time for validation (can be overridden).
 268  * @param rrset: to be validated.
 269  * @param dnskey: DNSKEY rrset, keyset to try.
 270  * @param sig_idx: which signature to try to validate.
 271  * @param sortree: reused sorted order. Stored in region. Pass NULL at start,
 272  *      and for a new rrset.
 273  * @param reason: if bogus, a string returned, fixed or alloced in scratch.
 274  * @return secure if any key signs *this* signature. bogus if no key signs it,
 275  *      or unchecked on error.
 276  */
 277 enum sec_status dnskeyset_verify_rrset_sig(struct module_env* env,
 278         struct val_env* ve, time_t now, struct ub_packed_rrset_key* rrset,
 279         struct ub_packed_rrset_key* dnskey, size_t sig_idx,
 280         struct rbtree_t** sortree, char** reason);
 281
 282 /**
 283  * verify rrset, with specific dnskey(from set), for a specific rrsig
 284  * @param region: scratch region used for temporary allocation.
 285  * @param buf: scratch buffer used for canonicalized rrset data.
 286  * @param ve: validator environment, date settings.
 287  * @param now: current time for validation (can be overridden).
 288  * @param rrset: to be validated.
 289  * @param dnskey: DNSKEY rrset, keyset.
 290  * @param dnskey_idx: which key from the rrset to try.
 291  * @param sig_idx: which signature to try to validate.
 292  * @param sortree: pass NULL at start, the sorted rrset order is returned.
 293  *      pass it again for the same rrset.
 294  * @param buf_canon: if true, the buffer is already canonical.
 295  *      pass false at start. pass old value only for same rrset and same
 296  *      signature (but perhaps different key) for reuse.
 297  * @param reason: if bogus, a string returned, fixed or alloced in scratch.
 298  * @return secure if this key signs this signature. unchecked on error or
 299  *      bogus if it did not validate.
 300  */
 301 enum sec_status dnskey_verify_rrset_sig(struct regional* region,
 302         struct sldns_buffer* buf, struct val_env* ve, time_t now,
 303         struct ub_packed_rrset_key* rrset, struct ub_packed_rrset_key* dnskey,
 304         size_t dnskey_idx, size_t sig_idx,
 305         struct rbtree_t** sortree, int* buf_canon, char** reason);
 306
 307 /**
 308  * canonical compare for two tree entries
 309  */
 310 int canonical_tree_compare(const void* k1, const void* k2);
 311
 312 /**
 313  * Compare two rrsets and see if they are the same, canonicalised.
 314  * The rrsets are not altered.
 315  * @param region: temporary region.
 316  * @param k1: rrset1
 317  * @param k2: rrset2
 318  * @return true if equal.
 319  */
 320 int rrset_canonical_equal(struct regional* region,
 321         struct ub_packed_rrset_key* k1, struct ub_packed_rrset_key* k2);
 322
 323 #endif /* VALIDATOR_VAL_SIGCRYPT_H */