1/*	$NetBSD: hash.h,v 1.2 2024/08/18 20:47:14 christos 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.12 2009/01/17 23:47:43 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 ***/
84ISC_LANG_BEGINDECLS
85
86isc_result_t
87isc_hash_ctxcreate(isc_mem_t *mctx, isc_entropy_t *entropy, unsigned int limit,
88		   isc_hash_t **hctx);
89isc_result_t
90isc_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
107void
108isc_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
115void
116isc_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
124void
125isc_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/*@{*/
135void
136isc_hash_ctxinit(isc_hash_t *hctx);
137void
138isc_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/*@{*/
159unsigned int
160isc_hash_ctxcalc(isc_hash_t *hctx, const unsigned char *key,
161		 unsigned int keylen, isc_boolean_t case_sensitive);
162unsigned int
163isc_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
185ISC_LANG_ENDDECLS
186
187#endif /* ISC_HASH_H */
188