hash.h revision 290001 
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 */
186