/contrib/bind9/lib/isc/include/isc/hash.h

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