1 /* $NetBSD: hash.h,v 1.5 2014/12/10 04:38:00 christos Exp $ */ 2 3 /* 4 * Copyright (C) 2004-2007, 2009, 2013, 2014 Internet Systems Consortium, Inc. ("ISC") 5 * Copyright (C) 2003 Internet Software Consortium. 6 * 7 * Permission to use, copy, modify, and/or distribute this software for any 8 * purpose with or without fee is hereby granted, provided that the above 9 * copyright notice and this permission notice appear in all copies. 10 * 11 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 12 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 13 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 14 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 15 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 16 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 17 * PERFORMANCE OF THIS SOFTWARE. 18 */ 19 20 /* Id: hash.h,v 1.12 2009/01/17 23:47:43 tbox Exp */ 21 22 #ifndef ISC_HASH_H 23 #define ISC_HASH_H 1 24 25 #include <isc/types.h> 26 27 /***** 28 ***** Module Info 29 *****/ 30 31 /*! \file isc/hash.h 32 * 33 * \brief The hash API 34 * provides an unpredictable hash value for variable length data. 35 * A hash object contains a random vector (which is hidden from clients 36 * of this API) to make the actual hash value unpredictable. 37 * 38 * The algorithm used in the API guarantees the probability of hash 39 * collision; in the current implementation, as long as the values stored 40 * in the random vector are unpredictable, the probability of hash 41 * collision between arbitrary two different values is at most 1/2^16. 42 * 43 * Although the API is generic about the hash keys, it mainly expects 44 * DNS names (and sometimes IPv4/v6 addresses) as inputs. It has an 45 * upper limit of the input length, and may run slow to calculate the 46 * hash values for large inputs. 47 * 48 * This API is designed to be general so that it can provide multiple 49 * different hash contexts that have different random vectors. However, 50 * it should be typical to have a single context for an entire system. 51 * To support such cases, the API also provides a single-context mode. 52 * 53 * \li MP: 54 * The hash object is almost read-only. Once the internal random vector 55 * is initialized, no write operation will occur, and there will be no 56 * need to lock the object to calculate actual hash values. 57 * 58 * \li Reliability: 59 * In some cases this module uses low-level data copy to initialize the 60 * random vector. Errors in this part are likely to crash the server or 61 * corrupt memory. 62 * 63 * \li Resources: 64 * A buffer, used as a random vector for calculating hash values. 65 * 66 * \li Security: 67 * This module intends to provide unpredictable hash values in 68 * adversarial environments in order to avoid denial of service attacks 69 * to hash buckets. 70 * Its unpredictability relies on the quality of entropy to build the 71 * random vector. 72 * 73 * \li Standards: 74 * None. 75 */ 76 77 /*** 78 *** Imports 79 ***/ 80 81 #include <isc/types.h> 82 83 /*** 84 *** Functions 85 ***/ 86 ISC_LANG_BEGINDECLS 87 88 isc_result_t 89 isc_hash_ctxcreate(isc_mem_t *mctx, isc_entropy_t *entropy, size_t limit, 90 isc_hash_t **hctx); 91 isc_result_t 92 isc_hash_create(isc_mem_t *mctx, isc_entropy_t *entropy, size_t limit); 93 /*!< 94 * \brief Create a new hash object. 95 * 96 * isc_hash_ctxcreate() creates a different object. 97 * 98 * isc_hash_create() creates a module-internal object to support the 99 * single-context mode. It should be called only once. 100 * 101 * 'entropy' must be NULL or a valid entropy object. If 'entropy' is NULL, 102 * pseudo random values will be used to build the random vector, which may 103 * weaken security. 104 * 105 * 'limit' specifies the maximum number of hash keys. If it is too large, 106 * these functions may fail. 107 */ 108 109 void 110 isc_hash_ctxattach(isc_hash_t *hctx, isc_hash_t **hctxp); 111 /*!< 112 * \brief Attach to a hash object. 113 * 114 * This function is only necessary for the multiple-context mode. 115 */ 116 117 void 118 isc_hash_ctxdetach(isc_hash_t **hctxp); 119 /*!< 120 * \brief Detach from a hash object. 121 * 122 * This function is for the multiple-context mode, and takes a valid 123 * hash object as an argument. 124 */ 125 126 void 127 isc_hash_destroy(void); 128 /*!< 129 * \brief This function is for the single-context mode, and is expected to be used 130 * as a counterpart of isc_hash_create(). 131 * 132 * A valid module-internal hash object must have been created, and this 133 * function should be called only once. 134 */ 135 136 /*@{*/ 137 void 138 isc_hash_ctxinit(isc_hash_t *hctx); 139 void 140 isc_hash_init(void); 141 /*!< 142 * \brief Initialize a hash object. 143 * 144 * It fills in the random vector with a proper 145 * source of entropy, which is typically from the entropy object specified 146 * at the creation. Thus, it is desirable to call these functions after 147 * initializing the entropy object with some good entropy sources. 148 * 149 * These functions should be called before the first hash calculation. 150 * 151 * isc_hash_ctxinit() is for the multiple-context mode, and takes a valid hash 152 * object as an argument. 153 * 154 * isc_hash_init() is for the single-context mode. A valid module-internal 155 * hash object must have been created, and this function should be called only 156 * once. 157 */ 158 /*@}*/ 159 160 /*@{*/ 161 unsigned int 162 isc_hash_ctxcalc(isc_hash_t *hctx, const unsigned char *key, 163 unsigned int keylen, isc_boolean_t case_sensitive); 164 unsigned int 165 isc_hash_calc(const unsigned char *key, unsigned int keylen, 166 isc_boolean_t case_sensitive); 167 /*!< 168 * \brief Calculate a hash value. 169 * 170 * isc_hash_ctxinit() is for the multiple-context mode, and takes a valid hash 171 * object as an argument. 172 * 173 * isc_hash_init() is for the single-context mode. A valid module-internal 174 * hash object must have been created. 175 * 176 * 'key' is the hash key, which is a variable length buffer. 177 * 178 * 'keylen' specifies the key length, which must not be larger than the limit 179 * specified for the corresponding hash object. 180 * 181 * 'case_sensitive' specifies whether the hash key should be treated as 182 * case_sensitive values. It should typically be ISC_FALSE if the hash key 183 * is a DNS name. 184 */ 185 /*@}*/ 186 187 void 188 isc__hash_setvec(const isc_uint16_t *vec); 189 190 /*!< 191 * \brief Set the contents of the random vector used in hashing. 192 * 193 * WARNING: This function is meant to be used only in testing code. It 194 * must not be used anywhere in normally running code. 195 * 196 * The hash context must have been created beforehand, otherwise this 197 * function is a nop. 198 * 199 * 'vec' is not documented here on purpose. You should know what you are 200 * doing before using this function. 201 */ 202 203 ISC_LANG_ENDDECLS 204 205 #endif /* ISC_HASH_H */ 206