1290001Sglebius/* 2290001Sglebius * Copyright (C) 2004-2007, 2009 Internet Systems Consortium, Inc. ("ISC") 3290001Sglebius * Copyright (C) 2003 Internet Software Consortium. 4290001Sglebius * 5290001Sglebius * Permission to use, copy, modify, and/or distribute this software for any 6290001Sglebius * purpose with or without fee is hereby granted, provided that the above 7290001Sglebius * copyright notice and this permission notice appear in all copies. 8290001Sglebius * 9290001Sglebius * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10290001Sglebius * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11290001Sglebius * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12290001Sglebius * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13290001Sglebius * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14290001Sglebius * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15290001Sglebius * PERFORMANCE OF THIS SOFTWARE. 16290001Sglebius */ 17290001Sglebius 18290001Sglebius/* $Id: hash.h,v 1.12 2009/01/17 23:47:43 tbox Exp $ */ 19290001Sglebius 20290001Sglebius#ifndef ISC_HASH_H 21290001Sglebius#define ISC_HASH_H 1 22290001Sglebius 23290001Sglebius/***** 24290001Sglebius ***** Module Info 25290001Sglebius *****/ 26290001Sglebius 27290001Sglebius/*! \file isc/hash.h 28290001Sglebius * 29290001Sglebius * \brief The hash API 30290001Sglebius * provides an unpredictable hash value for variable length data. 31290001Sglebius * A hash object contains a random vector (which is hidden from clients 32290001Sglebius * of this API) to make the actual hash value unpredictable. 33290001Sglebius * 34290001Sglebius * The algorithm used in the API guarantees the probability of hash 35290001Sglebius * collision; in the current implementation, as long as the values stored 36290001Sglebius * in the random vector are unpredictable, the probability of hash 37290001Sglebius * collision between arbitrary two different values is at most 1/2^16. 38290001Sglebius * 39290001Sglebius * Although the API is generic about the hash keys, it mainly expects 40290001Sglebius * DNS names (and sometimes IPv4/v6 addresses) as inputs. It has an 41290001Sglebius * upper limit of the input length, and may run slow to calculate the 42290001Sglebius * hash values for large inputs. 43290001Sglebius * 44290001Sglebius * This API is designed to be general so that it can provide multiple 45290001Sglebius * different hash contexts that have different random vectors. However, 46290001Sglebius * it should be typical to have a single context for an entire system. 47290001Sglebius * To support such cases, the API also provides a single-context mode. 48290001Sglebius * 49290001Sglebius * \li MP: 50290001Sglebius * The hash object is almost read-only. Once the internal random vector 51290001Sglebius * is initialized, no write operation will occur, and there will be no 52290001Sglebius * need to lock the object to calculate actual hash values. 53290001Sglebius * 54290001Sglebius * \li Reliability: 55290001Sglebius * In some cases this module uses low-level data copy to initialize the 56290001Sglebius * random vector. Errors in this part are likely to crash the server or 57290001Sglebius * corrupt memory. 58290001Sglebius * 59290001Sglebius * \li Resources: 60290001Sglebius * A buffer, used as a random vector for calculating hash values. 61290001Sglebius * 62290001Sglebius * \li Security: 63290001Sglebius * This module intends to provide unpredictable hash values in 64290001Sglebius * adversarial environments in order to avoid denial of service attacks 65290001Sglebius * to hash buckets. 66290001Sglebius * Its unpredictability relies on the quality of entropy to build the 67290001Sglebius * random vector. 68290001Sglebius * 69290001Sglebius * \li Standards: 70290001Sglebius * None. 71290001Sglebius */ 72290001Sglebius 73290001Sglebius/*** 74290001Sglebius *** Imports 75290001Sglebius ***/ 76290001Sglebius 77290001Sglebius#include <isc/types.h> 78290001Sglebius 79290001Sglebius/*** 80290001Sglebius *** Functions 81290001Sglebius ***/ 82290001SglebiusISC_LANG_BEGINDECLS 83290001Sglebius 84290001Sglebiusisc_result_t 85290001Sglebiusisc_hash_ctxcreate(isc_mem_t *mctx, isc_entropy_t *entropy, unsigned int limit, 86290001Sglebius isc_hash_t **hctx); 87290001Sglebiusisc_result_t 88290001Sglebiusisc_hash_create(isc_mem_t *mctx, isc_entropy_t *entropy, size_t limit); 89290001Sglebius/*!< 90290001Sglebius * \brief Create a new hash object. 91290001Sglebius * 92290001Sglebius * isc_hash_ctxcreate() creates a different object. 93290001Sglebius * 94290001Sglebius * isc_hash_create() creates a module-internal object to support the 95290001Sglebius * single-context mode. It should be called only once. 96290001Sglebius * 97290001Sglebius * 'entropy' must be NULL or a valid entropy object. If 'entropy' is NULL, 98290001Sglebius * pseudo random values will be used to build the random vector, which may 99290001Sglebius * weaken security. 100290001Sglebius * 101290001Sglebius * 'limit' specifies the maximum number of hash keys. If it is too large, 102290001Sglebius * these functions may fail. 103290001Sglebius */ 104290001Sglebius 105290001Sglebiusvoid 106290001Sglebiusisc_hash_ctxattach(isc_hash_t *hctx, isc_hash_t **hctxp); 107290001Sglebius/*!< 108290001Sglebius * \brief Attach to a hash object. 109290001Sglebius * 110290001Sglebius * This function is only necessary for the multiple-context mode. 111290001Sglebius */ 112290001Sglebius 113290001Sglebiusvoid 114290001Sglebiusisc_hash_ctxdetach(isc_hash_t **hctxp); 115290001Sglebius/*!< 116290001Sglebius * \brief Detach from a hash object. 117290001Sglebius * 118290001Sglebius * This function is for the multiple-context mode, and takes a valid 119290001Sglebius * hash object as an argument. 120290001Sglebius */ 121290001Sglebius 122290001Sglebiusvoid 123290001Sglebiusisc_hash_destroy(void); 124290001Sglebius/*!< 125290001Sglebius * \brief This function is for the single-context mode, and is expected to be used 126290001Sglebius * as a counterpart of isc_hash_create(). 127290001Sglebius * 128290001Sglebius * A valid module-internal hash object must have been created, and this 129290001Sglebius * function should be called only once. 130290001Sglebius */ 131290001Sglebius 132290001Sglebius/*@{*/ 133290001Sglebiusvoid 134290001Sglebiusisc_hash_ctxinit(isc_hash_t *hctx); 135290001Sglebiusvoid 136290001Sglebiusisc_hash_init(void); 137290001Sglebius/*!< 138290001Sglebius * \brief Initialize a hash object. 139290001Sglebius * 140290001Sglebius * It fills in the random vector with a proper 141290001Sglebius * source of entropy, which is typically from the entropy object specified 142290001Sglebius * at the creation. Thus, it is desirable to call these functions after 143290001Sglebius * initializing the entropy object with some good entropy sources. 144290001Sglebius * 145290001Sglebius * These functions should be called before the first hash calculation. 146290001Sglebius * 147290001Sglebius * isc_hash_ctxinit() is for the multiple-context mode, and takes a valid hash 148290001Sglebius * object as an argument. 149290001Sglebius * 150290001Sglebius * isc_hash_init() is for the single-context mode. A valid module-internal 151290001Sglebius * hash object must have been created, and this function should be called only 152290001Sglebius * once. 153290001Sglebius */ 154290001Sglebius/*@}*/ 155290001Sglebius 156290001Sglebius/*@{*/ 157290001Sglebiusunsigned int 158290001Sglebiusisc_hash_ctxcalc(isc_hash_t *hctx, const unsigned char *key, 159290001Sglebius unsigned int keylen, isc_boolean_t case_sensitive); 160290001Sglebiusunsigned int 161290001Sglebiusisc_hash_calc(const unsigned char *key, unsigned int keylen, 162290001Sglebius isc_boolean_t case_sensitive); 163290001Sglebius/*!< 164290001Sglebius * \brief Calculate a hash value. 165290001Sglebius * 166290001Sglebius * isc_hash_ctxinit() is for the multiple-context mode, and takes a valid hash 167290001Sglebius * object as an argument. 168290001Sglebius * 169290001Sglebius * isc_hash_init() is for the single-context mode. A valid module-internal 170290001Sglebius * hash object must have been created. 171290001Sglebius * 172290001Sglebius * 'key' is the hash key, which is a variable length buffer. 173290001Sglebius * 174290001Sglebius * 'keylen' specifies the key length, which must not be larger than the limit 175290001Sglebius * specified for the corresponding hash object. 176290001Sglebius * 177290001Sglebius * 'case_sensitive' specifies whether the hash key should be treated as 178290001Sglebius * case_sensitive values. It should typically be ISC_FALSE if the hash key 179290001Sglebius * is a DNS name. 180290001Sglebius */ 181290001Sglebius/*@}*/ 182290001Sglebius 183290001SglebiusISC_LANG_ENDDECLS 184290001Sglebius 185290001Sglebius#endif /* ISC_HASH_H */ 186