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

https://bitbucket.org/freebsd/freebsd-head/ · C++ Header · 185 lines · 27 code · 15 blank · 143 comment · 0 complexity · bb8bea6b5632dea570303bd34bd9f77b MD5 · raw file

  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. /* $Id: hash.h,v 1.12 2009/01/17 23:47:43 tbox Exp $ */
  18. #ifndef ISC_HASH_H
  19. #define ISC_HASH_H 1
  20. /*****
  21. ***** Module Info
  22. *****/
  23. /*! \file isc/hash.h
  24. *
  25. * \brief The hash API
  26. * provides an unpredictable hash value for variable length data.
  27. * A hash object contains a random vector (which is hidden from clients
  28. * of this API) to make the actual hash value unpredictable.
  29. *
  30. * The algorithm used in the API guarantees the probability of hash
  31. * collision; in the current implementation, as long as the values stored
  32. * in the random vector are unpredictable, the probability of hash
  33. * collision between arbitrary two different values is at most 1/2^16.
  34. *
  35. * Although the API is generic about the hash keys, it mainly expects
  36. * DNS names (and sometimes IPv4/v6 addresses) as inputs. It has an
  37. * upper limit of the input length, and may run slow to calculate the
  38. * hash values for large inputs.
  39. *
  40. * This API is designed to be general so that it can provide multiple
  41. * different hash contexts that have different random vectors. However,
  42. * it should be typical to have a single context for an entire system.
  43. * To support such cases, the API also provides a single-context mode.
  44. *
  45. * \li MP:
  46. * The hash object is almost read-only. Once the internal random vector
  47. * is initialized, no write operation will occur, and there will be no
  48. * need to lock the object to calculate actual hash values.
  49. *
  50. * \li Reliability:
  51. * In some cases this module uses low-level data copy to initialize the
  52. * random vector. Errors in this part are likely to crash the server or
  53. * corrupt memory.
  54. *
  55. * \li Resources:
  56. * A buffer, used as a random vector for calculating hash values.
  57. *
  58. * \li Security:
  59. * This module intends to provide unpredictable hash values in
  60. * adversarial environments in order to avoid denial of service attacks
  61. * to hash buckets.
  62. * Its unpredictability relies on the quality of entropy to build the
  63. * random vector.
  64. *
  65. * \li Standards:
  66. * None.
  67. */
  68. /***
  69. *** Imports
  70. ***/
  71. #include <isc/types.h>
  72. /***
  73. *** Functions
  74. ***/
  75. ISC_LANG_BEGINDECLS
  76. isc_result_t
  77. isc_hash_ctxcreate(isc_mem_t *mctx, isc_entropy_t *entropy, unsigned int limit,
  78. isc_hash_t **hctx);
  79. isc_result_t
  80. isc_hash_create(isc_mem_t *mctx, isc_entropy_t *entropy, size_t limit);
  81. /*!<
  82. * \brief Create a new hash object.
  83. *
  84. * isc_hash_ctxcreate() creates a different object.
  85. *
  86. * isc_hash_create() creates a module-internal object to support the
  87. * single-context mode. It should be called only once.
  88. *
  89. * 'entropy' must be NULL or a valid entropy object. If 'entropy' is NULL,
  90. * pseudo random values will be used to build the random vector, which may
  91. * weaken security.
  92. *
  93. * 'limit' specifies the maximum number of hash keys. If it is too large,
  94. * these functions may fail.
  95. */
  96. void
  97. isc_hash_ctxattach(isc_hash_t *hctx, isc_hash_t **hctxp);
  98. /*!<
  99. * \brief Attach to a hash object.
  100. *
  101. * This function is only necessary for the multiple-context mode.
  102. */
  103. void
  104. isc_hash_ctxdetach(isc_hash_t **hctxp);
  105. /*!<
  106. * \brief Detach from a hash object.
  107. *
  108. * This function is for the multiple-context mode, and takes a valid
  109. * hash object as an argument.
  110. */
  111. void
  112. isc_hash_destroy(void);
  113. /*!<
  114. * \brief This function is for the single-context mode, and is expected to be used
  115. * as a counterpart of isc_hash_create().
  116. *
  117. * A valid module-internal hash object must have been created, and this
  118. * function should be called only once.
  119. */
  120. /*@{*/
  121. void
  122. isc_hash_ctxinit(isc_hash_t *hctx);
  123. void
  124. isc_hash_init(void);
  125. /*!<
  126. * \brief Initialize a hash object.
  127. *
  128. * It fills in the random vector with a proper
  129. * source of entropy, which is typically from the entropy object specified
  130. * at the creation. Thus, it is desirable to call these functions after
  131. * initializing the entropy object with some good entropy sources.
  132. *
  133. * These functions should be called before the first hash calculation.
  134. *
  135. * isc_hash_ctxinit() is for the multiple-context mode, and takes a valid hash
  136. * object as an argument.
  137. *
  138. * isc_hash_init() is for the single-context mode. A valid module-internal
  139. * hash object must have been created, and this function should be called only
  140. * once.
  141. */
  142. /*@}*/
  143. /*@{*/
  144. unsigned int
  145. isc_hash_ctxcalc(isc_hash_t *hctx, const unsigned char *key,
  146. unsigned int keylen, isc_boolean_t case_sensitive);
  147. unsigned int
  148. isc_hash_calc(const unsigned char *key, unsigned int keylen,
  149. isc_boolean_t case_sensitive);
  150. /*!<
  151. * \brief Calculate a hash value.
  152. *
  153. * isc_hash_ctxinit() is for the multiple-context mode, and takes a valid hash
  154. * object as an argument.
  155. *
  156. * isc_hash_init() is for the single-context mode. A valid module-internal
  157. * hash object must have been created.
  158. *
  159. * 'key' is the hash key, which is a variable length buffer.
  160. *
  161. * 'keylen' specifies the key length, which must not be larger than the limit
  162. * specified for the corresponding hash object.
  163. *
  164. * 'case_sensitive' specifies whether the hash key should be treated as
  165. * case_sensitive values. It should typically be ISC_FALSE if the hash key
  166. * is a DNS name.
  167. */
  168. /*@}*/
  169. ISC_LANG_ENDDECLS
  170. #endif /* ISC_HASH_H */