hash.h

Go to the documentation of this file.
00001 /*
00002  * Copyright (C) 2004-2007, 2009, 2013, 2014  Internet Systems Consortium, Inc. ("ISC")
00003  * Copyright (C) 2003  Internet Software Consortium.
00004  *
00005  * Permission to use, copy, modify, and/or distribute this software for any
00006  * purpose with or without fee is hereby granted, provided that the above
00007  * copyright notice and this permission notice appear in all copies.
00008  *
00009  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
00010  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
00011  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
00012  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
00013  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
00014  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
00015  * PERFORMANCE OF THIS SOFTWARE.
00016  */
00017 
00018 /* $Id: hash.h,v 1.12 2009/01/17 23:47:43 tbox Exp $ */
00019 
00020 #ifndef ISC_HASH_H
00021 #define ISC_HASH_H 1
00022 
00023 #include <isc/types.h>
00024 
00025 /*****
00026  ***** Module Info
00027  *****/
00028 
00029 /*! \file isc/hash.h
00030  *
00031  * \brief The hash API
00032  *      provides an unpredictable hash value for variable length data.
00033  *      A hash object contains a random vector (which is hidden from clients
00034  *      of this API) to make the actual hash value unpredictable.
00035  *
00036  *      The algorithm used in the API guarantees the probability of hash
00037  *      collision; in the current implementation, as long as the values stored
00038  *      in the random vector are unpredictable, the probability of hash
00039  *      collision between arbitrary two different values is at most 1/2^16.
00040  *
00041  *      Although the API is generic about the hash keys, it mainly expects
00042  *      DNS names (and sometimes IPv4/v6 addresses) as inputs.  It has an
00043  *      upper limit of the input length, and may run slow to calculate the
00044  *      hash values for large inputs.
00045  *
00046  *      This API is designed to be general so that it can provide multiple
00047  *      different hash contexts that have different random vectors.  However,
00048  *      it should be typical to have a single context for an entire system.
00049  *      To support such cases, the API also provides a single-context mode.
00050  *
00051  * \li MP:
00052  *      The hash object is almost read-only.  Once the internal random vector
00053  *      is initialized, no write operation will occur, and there will be no
00054  *      need to lock the object to calculate actual hash values.
00055  *
00056  * \li Reliability:
00057  *      In some cases this module uses low-level data copy to initialize the
00058  *      random vector.  Errors in this part are likely to crash the server or
00059  *      corrupt memory.
00060  *
00061  * \li Resources:
00062  *      A buffer, used as a random vector for calculating hash values.
00063  *
00064  * \li Security:
00065  *      This module intends to provide unpredictable hash values in
00066  *      adversarial environments in order to avoid denial of service attacks
00067  *      to hash buckets.
00068  *      Its unpredictability relies on the quality of entropy to build the
00069  *      random vector.
00070  *
00071  * \li Standards:
00072  *      None.
00073  */
00074 
00075 /***
00076  *** Imports
00077  ***/
00078 
00079 #include <isc/types.h>
00080 
00081 /***
00082  *** Functions
00083  ***/
00084 ISC_LANG_BEGINDECLS
00085 
00086 isc_result_t
00087 isc_hash_ctxcreate(isc_mem_t *mctx, isc_entropy_t *entropy, size_t limit,
00088                    isc_hash_t **hctx);
00089 isc_result_t
00090 isc_hash_create(isc_mem_t *mctx, isc_entropy_t *entropy, size_t limit);
00091 /*!<
00092  * \brief Create a new hash object.
00093  *
00094  * isc_hash_ctxcreate() creates a different object.
00095  *
00096  * isc_hash_create() creates a module-internal object to support the
00097  * single-context mode.  It should be called only once.
00098  *
00099  * 'entropy' must be NULL or a valid entropy object.  If 'entropy' is NULL,
00100  * pseudo random values will be used to build the random vector, which may
00101  * weaken security.
00102  *
00103  * 'limit' specifies the maximum number of hash keys.  If it is too large,
00104  * these functions may fail.
00105  */
00106 
00107 void
00108 isc_hash_ctxattach(isc_hash_t *hctx, isc_hash_t **hctxp);
00109 /*!<
00110  * \brief Attach to a hash object.
00111  *
00112  * This function is only necessary for the multiple-context mode.
00113  */
00114 
00115 void
00116 isc_hash_ctxdetach(isc_hash_t **hctxp);
00117 /*!<
00118  * \brief Detach from a hash object.
00119  *
00120  * This function  is for the multiple-context mode, and takes a valid
00121  * hash object as an argument.
00122  */
00123 
00124 void
00125 isc_hash_destroy(void);
00126 /*!<
00127  * \brief This function is for the single-context mode, and is expected to be used
00128  * as a counterpart of isc_hash_create().
00129  *
00130  * A valid module-internal hash object must have been created, and this
00131  * function should be called only once.
00132  */
00133 
00134 /*@{*/
00135 void
00136 isc_hash_ctxinit(isc_hash_t *hctx);
00137 void
00138 isc_hash_init(void);
00139 /*!<
00140  * \brief Initialize a hash object.
00141  *
00142  * It fills in the random vector with a proper
00143  * source of entropy, which is typically from the entropy object specified
00144  * at the creation.  Thus, it is desirable to call these functions after
00145  * initializing the entropy object with some good entropy sources.
00146  *
00147  * These functions should be called before the first hash calculation.
00148  *
00149  * isc_hash_ctxinit() is for the multiple-context mode, and takes a valid hash
00150  * object as an argument.
00151  *
00152  * isc_hash_init() is for the single-context mode.  A valid module-internal
00153  * hash object must have been created, and this function should be called only
00154  * once.
00155  */
00156 /*@}*/
00157 
00158 /*@{*/
00159 unsigned int
00160 isc_hash_ctxcalc(isc_hash_t *hctx, const unsigned char *key,
00161                  unsigned int keylen, isc_boolean_t case_sensitive);
00162 unsigned int
00163 isc_hash_calc(const unsigned char *key, unsigned int keylen,
00164               isc_boolean_t case_sensitive);
00165 /*!<
00166  * \brief Calculate a hash value.
00167  *
00168  * isc_hash_ctxinit() is for the multiple-context mode, and takes a valid hash
00169  * object as an argument.
00170  *
00171  * isc_hash_init() is for the single-context mode.  A valid module-internal
00172  * hash object must have been created.
00173  *
00174  * 'key' is the hash key, which is a variable length buffer.
00175  *
00176  * 'keylen' specifies the key length, which must not be larger than the limit
00177  * specified for the corresponding hash object.
00178  *
00179  * 'case_sensitive' specifies whether the hash key should be treated as
00180  * case_sensitive values.  It should typically be ISC_FALSE if the hash key
00181  * is a DNS name.
00182  */
00183 /*@}*/
00184 
00185 void
00186 isc__hash_setvec(const isc_uint16_t *vec);
00187 
00188 /*!<
00189  * \brief Set the contents of the random vector used in hashing.
00190  *
00191  * WARNING: This function is meant to be used only in testing code. It
00192  * must not be used anywhere in normally running code.
00193  *
00194  * The hash context must have been created beforehand, otherwise this
00195  * function is a nop.
00196  *
00197  * 'vec' is not documented here on purpose. You should know what you are
00198  * doing before using this function.
00199  */
00200 
00201 ISC_LANG_ENDDECLS
00202 
00203 #endif /* ISC_HASH_H */

Generated on Tue Apr 28 17:41:04 2015 by Doxygen 1.5.4 for BIND9 Internals 9.11.0pre-alpha