1 /* $NetBSD: hash.h,v 1.1.1.1 2009/12/13 16:54:26 kardel Exp $ */ 2 3 /* 4 * Copyright (C) 2004-2007, 2009 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.10.332.2 2009/01/18 23:47:41 tbox Exp */ 21 22 #ifndef ISC_HASH_H 23 #define ISC_HASH_H 1 24 25 /***** 26 ***** Module Info 27 *****/ 28 29 /*! \file isc/hash.h 30 * 31 * \brief The hash API 32 * provides an unpredictable hash value for variable length data. 33 * A hash object contains a random vector (which is hidden from clients 34 * of this API) to make the actual hash value unpredictable. 35 * 36 * The algorithm used in the API guarantees the probability of hash 37 * collision; in the current implementation, as long as the values stored 38 * in the random vector are unpredictable, the probability of hash 39 * collision between arbitrary two different values is at most 1/2^16. 40 * 41 * Although the API is generic about the hash keys, it mainly expects 42 * DNS names (and sometimes IPv4/v6 addresses) as inputs. It has an 43 * upper limit of the input length, and may run slow to calculate the 44 * hash values for large inputs. 45 * 46 * This API is designed to be general so that it can provide multiple 47 * different hash contexts that have different random vectors. However, 48 * it should be typical to have a single context for an entire system. 49 * To support such cases, the API also provides a single-context mode. 50 * 51 * \li MP: 52 * The hash object is almost read-only. Once the internal random vector 53 * is initialized, no write operation will occur, and there will be no 54 * need to lock the object to calculate actual hash values. 55 * 56 * \li Reliability: 57 * In some cases this module uses low-level data copy to initialize the 58 * random vector. Errors in this part are likely to crash the server or 59 * corrupt memory. 60 * 61 * \li Resources: 62 * A buffer, used as a random vector for calculating hash values. 63 * 64 * \li Security: 65 * This module intends to provide unpredictable hash values in 66 * adversarial environments in order to avoid denial of service attacks 67 * to hash buckets. 68 * Its unpredictability relies on the quality of entropy to build the 69 * random vector. 70 * 71 * \li Standards: 72 * None. 73 */ 74 75 /*** 76 *** Imports 77 ***/ 78 79 #include <isc/types.h> 80 81 /*** 82 *** Functions 83 ***/ 84 ISC_LANG_BEGINDECLS 85 86 isc_result_t 87 isc_hash_ctxcreate(isc_mem_t *mctx, isc_entropy_t *entropy, unsigned int limit, 88 isc_hash_t **hctx); 89 isc_result_t 90 isc_hash_create(isc_mem_t *mctx, isc_entropy_t *entropy, size_t limit); 91 /*!< 92 * \brief Create a new hash object. 93 * 94 * isc_hash_ctxcreate() creates a different object. 95 * 96 * isc_hash_create() creates a module-internal object to support the 97 * single-context mode. It should be called only once. 98 * 99 * 'entropy' must be NULL or a valid entropy object. If 'entropy' is NULL, 100 * pseudo random values will be used to build the random vector, which may 101 * weaken security. 102 * 103 * 'limit' specifies the maximum number of hash keys. If it is too large, 104 * these functions may fail. 105 */ 106 107 void 108 isc_hash_ctxattach(isc_hash_t *hctx, isc_hash_t **hctxp); 109 /*!< 110 * \brief Attach to a hash object. 111 * 112 * This function is only necessary for the multiple-context mode. 113 */ 114 115 void 116 isc_hash_ctxdetach(isc_hash_t **hctxp); 117 /*!< 118 * \brief Detach from a hash object. 119 * 120 * This function is for the multiple-context mode, and takes a valid 121 * hash object as an argument. 122 */ 123 124 void 125 isc_hash_destroy(void); 126 /*!< 127 * \brief This function is for the single-context mode, and is expected to be used 128 * as a counterpart of isc_hash_create(). 129 * 130 * A valid module-internal hash object must have been created, and this 131 * function should be called only once. 132 */ 133 134 /*@{*/ 135 void 136 isc_hash_ctxinit(isc_hash_t *hctx); 137 void 138 isc_hash_init(void); 139 /*!< 140 * \brief Initialize a hash object. 141 * 142 * It fills in the random vector with a proper 143 * source of entropy, which is typically from the entropy object specified 144 * at the creation. Thus, it is desirable to call these functions after 145 * initializing the entropy object with some good entropy sources. 146 * 147 * These functions should be called before the first hash calculation. 148 * 149 * isc_hash_ctxinit() is for the multiple-context mode, and takes a valid hash 150 * object as an argument. 151 * 152 * isc_hash_init() is for the single-context mode. A valid module-internal 153 * hash object must have been created, and this function should be called only 154 * once. 155 */ 156 /*@}*/ 157 158 /*@{*/ 159 unsigned int 160 isc_hash_ctxcalc(isc_hash_t *hctx, const unsigned char *key, 161 unsigned int keylen, isc_boolean_t case_sensitive); 162 unsigned int 163 isc_hash_calc(const unsigned char *key, unsigned int keylen, 164 isc_boolean_t case_sensitive); 165 /*!< 166 * \brief Calculate a hash value. 167 * 168 * isc_hash_ctxinit() is for the multiple-context mode, and takes a valid hash 169 * object as an argument. 170 * 171 * isc_hash_init() is for the single-context mode. A valid module-internal 172 * hash object must have been created. 173 * 174 * 'key' is the hash key, which is a variable length buffer. 175 * 176 * 'keylen' specifies the key length, which must not be larger than the limit 177 * specified for the corresponding hash object. 178 * 179 * 'case_sensitive' specifies whether the hash key should be treated as 180 * case_sensitive values. It should typically be ISC_FALSE if the hash key 181 * is a DNS name. 182 */ 183 /*@}*/ 184 185 ISC_LANG_ENDDECLS 186 187 #endif /* ISC_HASH_H */ 188