unbound/validator/autotrust.h

   1 /*
   2  * validator/autotrust.h - RFC5011 trust anchor management for unbound.
   3  *
   4  * Copyright (c) 2009, 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  * Contains autotrust definitions.
  40  */
  41
  42 #ifndef VALIDATOR_AUTOTRUST_H
  43 #define VALIDATOR_AUTOTRUST_H
  44 #include "util/rbtree.h"
  45 #include "util/data/packed_rrset.h"
  46 struct val_anchors;
  47 struct trust_anchor;
  48 struct ub_packed_rrset_key;
  49 struct module_env;
  50 struct val_env;
  51 struct sldns_buffer;
  52
  53 /** Autotrust anchor states */
  54 typedef enum {
  55         AUTR_STATE_START   = 0,
  56         AUTR_STATE_ADDPEND = 1,
  57         AUTR_STATE_VALID   = 2,
  58         AUTR_STATE_MISSING = 3,
  59         AUTR_STATE_REVOKED = 4,
  60         AUTR_STATE_REMOVED = 5
  61 } autr_state_t;
  62
  63 /**
  64  * Autotrust metadata for one trust anchor key.
  65  */
  66 struct autr_ta {
  67         /** next key */
  68         struct autr_ta* next;
  69         /** the RR */
  70         uint8_t* rr;
  71         /** length of rr */
  72         size_t rr_len, dname_len;
  73         /** last update of key state (new pending count keeps date the same) */
  74         time_t last_change;
  75         /** 5011 state */
  76         autr_state_t s;
  77         /** pending count */
  78         uint8_t pending_count;
  79         /** fresh TA was seen */
  80         uint8_t fetched;
  81         /** revoked TA was seen */
  82         uint8_t revoked;
  83 };
  84
  85 /**
  86  * Autotrust metadata for a trust point.
  87  * This is part of the struct trust_anchor data.
  88  */
  89 struct autr_point_data {
  90         /** file to store the trust point in. chrootdir already applied. */
  91         char* file;
  92         /** rbtree node for probe sort, key is struct trust_anchor */
  93         rbnode_t pnode;
  94
  95         /** the keys */
  96         struct autr_ta* keys;
  97
  98         /** last queried DNSKEY set
  99          * Not all failures are captured in this entry.
 100          * If the validator did not even start (e.g. timeout or localservfail),
 101          * then the last_queried and query_failed values are not updated.
 102          */
 103         time_t last_queried;
 104         /** last successful DNSKEY set */
 105         time_t last_success;
 106         /** next probe time */
 107         time_t next_probe_time;
 108
 109         /** when to query if !failed */
 110         time_t query_interval;
 111         /** when to retry if failed */
 112         time_t retry_time;
 113
 114         /**
 115          * How many times did it fail. diagnostic only (has no effect).
 116          * Only updated if there was a dnskey rrset that failed to verify.
 117          */
 118         uint8_t query_failed;
 119         /** true if the trust point has been revoked */
 120         uint8_t revoked;
 121 };
 122
 123 /**
 124  * Autotrust global metadata.
 125  */
 126 struct autr_global_data {
 127         /** rbtree of autotrust anchors sorted by next probe time.
 128          * When time is equal, sorted by anchor class, name. */
 129         rbtree_t probe;
 130 };
 131
 132 /**
 133  * Create new global 5011 data structure.
 134  * @return new structure or NULL on malloc failure.
 135  */
 136 struct autr_global_data* autr_global_create(void);
 137
 138 /**
 139  * Delete global 5011 data structure.
 140  * @param global: global autotrust state to delete.
 141  */
 142 void autr_global_delete(struct autr_global_data* global);
 143
 144 /**
 145  * See if autotrust anchors are configured and how many.
 146  * @param anchors: the trust anchors structure.
 147  * @return number of autotrust trust anchors
 148  */
 149 size_t autr_get_num_anchors(struct val_anchors* anchors);
 150
 151 /**
 152  * Process probe timer.  Add new probes if needed.
 153  * @param env: module environment with time, with anchors and with the mesh.
 154  * @return time of next probe (in seconds from now).
 155  *      If 0, then there is no next probe anymore (trust points deleted).
 156  */
 157 time_t autr_probe_timer(struct module_env* env);
 158
 159 /** probe tree compare function */
 160 int probetree_cmp(const void* x, const void* y);
 161
 162 /**
 163  * Read autotrust file.
 164  * @param anchors: the anchors structure.
 165  * @param nm: name of the file (copied).
 166  * @return false on failure.
 167  */
 168 int autr_read_file(struct val_anchors* anchors, const char* nm);
 169
 170 /**
 171  * Write autotrust file.
 172  * @param env: environment with scratch space.
 173  * @param tp: trust point to write.
 174  */
 175 void autr_write_file(struct module_env* env, struct trust_anchor* tp);
 176
 177 /**
 178  * Delete autr anchor, deletes the autr data but does not do
 179  * unlinking from trees, caller does that.
 180  * @param tp: trust point to delete.
 181  */
 182 void autr_point_delete(struct trust_anchor* tp);
 183
 184 /**
 185  * Perform autotrust processing.
 186  * @param env: qstate environment with the anchors structure.
 187  * @param ve: validator environment for verification of rrsigs.
 188  * @param tp: trust anchor to process.
 189  * @param dnskey_rrset: DNSKEY rrset probed (can be NULL if bad prime result).
 190  *      allocated in a region. Has not been validated yet.
 191  * @return false if trust anchor was revoked completely.
 192  *      Otherwise logs errors to log, does not change return value.
 193  *      On errors, likely the trust point has been unchanged.
 194  */
 195 int autr_process_prime(struct module_env* env, struct val_env* ve,
 196         struct trust_anchor* tp, struct ub_packed_rrset_key* dnskey_rrset);
 197
 198 /**
 199  * Debug printout of rfc5011 tracked anchors
 200  * @param anchors: all the anchors.
 201  */
 202 void autr_debug_print(struct val_anchors* anchors);
 203
 204 /** callback for query answer to 5011 probe */
 205 void probe_answer_cb(void* arg, int rcode, struct sldns_buffer* buf,
 206         enum sec_status sec, char* errinf);
 207
 208 #endif /* VALIDATOR_AUTOTRUST_H */